# Camera Obscura<\/p>\n
<\/p>\n
Camera Obscura is a **server\u2011side software rasterizer** that renders the world as seen by any entity (player, mob, etc.) directly on the server, producing Photos or Videos as Minecraft **maps**.
\nIt has deep integrations for custom items (Nexo, ItemsAdder) and a custom preset system.<\/p>\n
—<\/p>\n
## Features<\/p>\n
– **Take photos**: Generate a map item showing what the target entity sees.
\n– **Record videos**: Capture your world on video and play it back on item frames.
\n– **Fully configurable**: Resolution, color mode, dithering, render distance, and more.
\n– **Custom item support**: Create cameras\/camcorders with any appearance via **Nexo** or **ItemsAdder**.
\n– **Asynchronous rendering**: Never blocks the main server thread.
\n– **No client mods required**: Everything is server\u2011side; maps\/recordings work on vanilla clients. <\/p>\n
<\/p>\n
—<\/p>\n
## Installation<\/p>\n
### Fabric Server
\n1. Install Fabric API and Polymer (for virtual items).
\n2. Place `camera-obscura-fabric.jar` into your `mods\/` folder.
\n3. The configuration file will be created on start.<\/p>\n
—<\/p>\n
## Configuration<\/p>\n
The configuration file is `config\/cameraobscura\/config.json`.<\/p>\n
“`json
\n{
\n “renderDistance”: 32,
\n “showSystemMessages”: false,
\n “renderEntities”: true,
\n “fullbright”: false,
\n “fov”: 70,
\n “biomeBlend”: 1,
\n “ssaa”: 2,
\n “maxChunkRebuildsPerTick”: 5,
\n “debug”: false,
\n “cameraConsumesItem”: true,
\n “cameraConsumeItem”: “map”,
\n “commandPermissionLevel”: 2
\n}
\n“`<\/p>\n
| Option | Description |
\n|—————————|——————————————————————————————|
\n| `renderDistance` | View distance in blocks (higher = longer render time). |
\n| `showSystemMessages` | Show \u201cTaking photo\u2026\u201d \/ \u201cDone!\u201d messages in chat. |
\n| `renderEntities` | Whether to render entities (players, mobs, item frames) in the picture. |
\n| `fullbright` | Ignore lighting (everything appears at full brightness). |
\n| `fov` | Field of view in degrees (default is 70). |
\n| `biomeBlend` | Radius for blending block colors (biome tint). `0` = no blending. |
\n| `ssaa` | Supersampling anti\u2011aliasing factor (1 = off, 2 = 2x supersampling, 3 = 3x). |
\n| `maxChunkRebuildsPerTick` | Maximum chunks rebuilt per frame per video recording and live-map (to limit CPU spikes). |
\n| `debug` | Print frame timings and show FPS overlay on the output image. |
\n| `cameraConsumesItem` | Whether taking a photo consumes an item (e.g. a map). |
\n| `cameraConsumeItem` | Required item material (e.g. `map`, `paper`). |
\n| `commandPermissionLevel` | Base permission level for commands. |<\/p>\n
—<\/p>\n
## Commands & Permissions<\/p>\n
**Base permission** `cameraobscura.command`.<\/p>\n
All commands use the root `\/camera-obscura`<\/p>\n
### 1. Take a map from your perspective
\n“`
\n\/camera-obscura [scale]
\n“`
\n– `scale`: multiply the map resolution (1 = 128\u00d7128, 2 = 256\u00d7256, up to 3).
\n– Gives you a **filled map** showing what *you* see.<\/p>\n
### 2. Take a map of another entities perspective ### 3. Save as PNG image ### 4. Reload configuration ### 5. Clear resource\/model cache ### 6. Give a camera item **Examples:** —<\/p>\n ## \ud83d\udcf7 Using the Camera Item<\/p>\n **Basic Camera** **Camcorder** —<\/p>\n # Components<\/p>\n The mod uses **data components** to store camera settings on the item stack. <\/p>\n This allows you to create cameras with different resolutions, color modes, and video parameters using standard commands, recipes, or loot tables.<\/p>\n ### Available Components<\/p>\n | Component ID | Type | Description | **DitherMode values**: —<\/p>\n ### Using Components in Commands<\/p>\n #### \/give #### \/item modify —<\/p>\n ### Using Components in Recipes<\/p>\n In a crafting recipes: For a camcorder (video mode), include `video`: —<\/p>\n ### Giving a Camcorder with Default Video Settings<\/p>\n The basic camcorder item (without components) uses global config defaults. To explicitly set video parameters: ## Built-in Items<\/p>\n On Fabric, Camera Obscura adds a few **built\u2011in camera and camcorder items** with pre\u2011configured settings (color mode, resolution, video parameters). <\/p>\n ### Camera Items (Photo Mode)<\/p>\n | Item ID | color Mode | Resolution | Dithering | ### Camcorder Items (Video Mode)<\/p>\n Record videos with pre\u2011set framerate and max frame count.<\/p>\n | Item ID | color Mode | Resolution | Dithering | Video (FPS \/ Max Frames) | **Usage example:** —<\/p>\n ## Video Playback<\/p>\n To play back a video maps:<\/p>\n – Place the map in an **item frame**. ## Presets<\/p>\n You can add your own presets, pre\u2011configured camera items with custom materials, display names, and camera settings (resolution, color mode, dither mode, video parameters). <\/p>\n Presets are stored in `presets.json` and can be given to players using the `\/camera-obscura give —<\/p>\n ### Preset Configuration Format<\/p>\n The `presets.json` file contains a JSON object where each key is a preset name and the value is an object with the following fields:<\/p>\n | Field | Description | #### Camera Options<\/p>\n All fields are optional<\/p>\n | Field | Type | Description | —<\/p>\n ### Default Presets<\/p>\n The mod ships with several ready\u2011to\u2011use presets. You can modify or delete them as you like.<\/p>\n “`json —<\/p>\n ### Using Presets in Commands<\/p>\n “`mcfunction Tab completion suggests available preset names.<\/p>\n ### Reloading Presets<\/p>\n After editing `presets.json` while the server is running, run:<\/p>\n “`mcfunction This reloads both the main configuration and all presets without restarting the server.<\/p>\n —<\/p>\n ## How It Works (Technical Overview)<\/p>\n Camera Obscura runs **completely on the server** and uses a **software rasterizer** to draw the scene pixel by pixel.<\/p>\n – The renderer requests chunks and entities around the target. ### Performance considerations —<\/p>\n ## Troubleshooting<\/p>\n | Problem | Check | —<\/p>\n","protected":false},"excerpt":{"rendered":" Take Photos of your world or server as Map Item, no client-side mods required!<\/p>\n","protected":false},"featured_media":36637,"template":"","meta":{"_minecraft_slug":"camera-obscura","_minecraft_project_id":"RlBTYKIp","_minecraft_author":"tomalbrc","_minecraft_license":"LGPL-3.0-only","_minecraft_downloads":12053,"_minecraft_follows":92,"_minecraft_client_side":"unsupported","_minecraft_server_side":"required","_minecraft_storage_type":"zip","_minecraft_archive_name":"camera-obscura.zip","_minecraft_size_bytes":20943140,"_minecraft_version_count":26,"_minecraft_updated_at":"2026-05-16T02:35:00.683965Z","_minecraft_date_created":"2024-05-21T23:17:57.584703Z","_minecraft_date_modified":"2026-05-14T18:03:12.949391Z","_minecraft_project_url":"https:\/\/modrinth.com\/mod\/camera-obscura","_minecraft_icon_attachment_id":36637,"_minecraft_imported_at":"2026-06-01T18:16:06+00:00","_minecraft_import_hash":"c44fe7f2137ae976934b3496504b3696","_minecraft_versions":"","_minecraft_links":"","_minecraft_gallery":"","_minecraft_api_metadata":""},"mod_category":[87,156,97,89,873,126,867,123],"mod_loader":[99],"minecraft_version":[36,94,102,62,37,40,41,73,749,750,74,38,78,79,80,81,82,800,83,167,163],"class_list":["post-36636","mod","type-mod","status-publish","has-post-thumbnail","hentry","mod_category-adventure","mod_category-decoration","mod_category-fabric","mod_category-game-mechanics","mod_category-library","mod_category-management","mod_category-social","mod_category-technology","mod_loader-fabric","minecraft_version-1-20-1","minecraft_version-1-20-4","minecraft_version-1-20-6","minecraft_version-1-21","minecraft_version-1-21-1","minecraft_version-1-21-10","minecraft_version-1-21-11","minecraft_version-1-21-2","minecraft_version-1-21-2-rc1","minecraft_version-1-21-2-rc2","minecraft_version-1-21-3","minecraft_version-1-21-4","minecraft_version-1-21-5","minecraft_version-1-21-6","minecraft_version-1-21-7","minecraft_version-1-21-8","minecraft_version-1-21-9","minecraft_version-1-21-9-rc1","minecraft_version-26-1","minecraft_version-26-1-1","minecraft_version-26-1-2"],"yoast_head":"\n
\n“`
\n\/camera-obscura
\n“`
\n– `
\n– `
\n“`
\n\/camera-obscura save [entity] [scale]
\n“`
\n– Saves the rendered image as a `.png` in `config\/cameraobscura\/renders\/`.<\/p>\n
\n“`
\n\/camera-obscura reload
\n“`
\nReloads the config file.<\/p>\n
\n“`
\n\/camera-obscura clear-cache
\n“`<\/p>\n
\n“`
\n\/camera-obscura give
\n“`
\n– `
\n– `[player]`: Optional player name; if omitted, gives the item to the command sender.<\/p>\n
\n– `\/camera-obscura give camera` -> gives yourself the default camera.
\n– `\/camera-obscura give camcorder Pinnit` -> gives the player `Pinnit` a camcorder.
\n– `\/camera-obscura give my-preset` -> gives yourself an item from a preset.<\/p>\n
\n– Hold the camera in your **main hand**.
\n– Right\u2011click -> after a countdown, the photo map item appears in your inventory (or drops on the ground if full).
\n– The map shows the world from *your* viewpoint at that moment. <\/p>\n
\n– Same controls, but starts **recording** instead of taking a single photo.
\n– The action-bar text indicates recording.
\n– Release to stop recording, the video will be saved as a map item that can be played back on item-frames.
\n– While recording, particles appear around the camera (frame effect).
\n– Videos are stored as APNG in `config\/cameraobscura\/camera_videos\/
\n|——————————–|——————————————————–|————————————————————————–|
\n| `camera-obscura:color` | `string` (ColorMode) | `”COLOR”`, `”MONOCHROME”`, `”GRAYSCALE”`, `”SEPIA”` |
\n| `camera-obscura:resolution` | `{width:int, height:int}` | Resolution in pixels (e.g. `{width:256, height:256}`) |
\n| `camera-obscura:dither` | `string` (DitherMode) | `”NONE”`, `”BAYER_2X2″`, `”FLOYD_STEINBERG”`, etc. (see full list below) |
\n| `camera-obscura:video` | `{frame_rate:int, max_frames:int, loop_playback:bool}` | Video recording parameters |
\n| `camera-obscura:map` | `unit` | Marks the item as a **live map** (internal) |
\n| `camera-obscura:camera_entity` | `entity_reference` | Stores the entity that took the photo (internal) |
\n| `camera-obscura:data` | `{id:uuid, video_params:…}` | Internal video data |<\/p>\n
\n`NONE`, `BAYER_2X2`, `BAYER_4X4`, `BAYER_8X8`, `FLOYD_STEINBERG`, `ATKINSON`, `JARVIS_JUDICE_NINKE`, `STUCKI`, `SIERRA`, `BURKES`<\/p>\n
\n“`mcfunction
\n\/give @p camera-obscura:camera[camera-obscura:color=”SEPIA”,camera-obscura:resolution={width:512,height:512},camera-obscura:dither=”FLOYD_STEINBERG”]
\n“`<\/p>\n
\nCreate a data pack with an item modifier:
\n“`json
\n{
\n “function”: “set_components”,
\n “components”: {
\n “camera-obscura:color”: “GRAYSCALE”,
\n “camera-obscura:resolution”: { “width”: 192, “height”: 192 },
\n “camera-obscura:dither”: “BAYER_8X8”
\n }
\n}
\n“`
\nThen run: `\/item modify entity @s weapon.mainhand my_pack:camera_settings`<\/p>\n
\n“`json
\n{
\n “type”: “minecraft:crafting_shaped”,
\n “pattern”: [“###”, “#P#”, “###”],
\n “key”: {
\n “#”: “minecraft:iron_ingot”,
\n “P”: “minecraft:ender_pearl”
\n },
\n “result”: {
\n “id”: “camera-obscura:camera”,
\n “components”: {
\n “camera-obscura:color”: “SEPIA”,
\n “camera-obscura:resolution”: { “width”: 128, “height”: 128 },
\n “camera-obscura:dither”: “NONE”
\n }
\n }
\n}
\n“`<\/p>\n
\n“`json
\n“components”: {
\n “camera-obscura:color”: “COLOR”,
\n “camera-obscura:resolution”: { “width”: 256, “height”: 256 },
\n “camera-obscura:video”: { “frame_rate”: 15, “max_frames”: 300 }
\n}
\n“`<\/p>\n
\n“`mcfunction
\n\/give @s camera-obscura:camcorder[camera-obscura:video={frame_rate:10,max_frames:200,loop_playback:true}]
\n“`<\/p>\n
\n|———————————–|————–|————|———–|
\n| `camera-obscura:camera` | `COLOR` | 128\u00d7128 | `NONE` |
\n| `camera-obscura:grayscale_camera` | `GRAYSCALE` | 128\u00d7128 | `NONE` |
\n| `camera-obscura:primitive_camera` | `MONOCHROME` | 128\u00d7128 | `NONE` |
\n| `camera-obscura:retro_camera` | `SEPIA` | 128\u00d7128 | `NONE` |<\/p>\n
\n|————————————–|————–|————|———–|————————–|
\n| `camera-obscura:camcorder` | `COLOR` | 128\u00d7128 | `NONE` | 10 FPS \/ 400 frames |
\n| `camera-obscura:grayscale_camcorder` | `GRAYSCALE` | 128\u00d7128 | `NONE` | 20 FPS \/ 400 frames |
\n| `camera-obscura:primitive_camcorder` | `MONOCHROME` | 128\u00d7128 | `NONE` | 20 FPS \/ 400 frames |
\n| `camera-obscura:retro_camcorder` | `SEPIA` | 128\u00d7128 | `NONE` | 20 FPS \/ 400 frames |<\/p>\n
\n“`mcfunction
\n\/give @s camera-obscura:grayscale_camera
\n“`<\/p>\n
\n– Right\u2011click the item frame and the video will start playing on the map.
\n– Right\u2011click again to stop playback.<\/p>\n
\n|————–|———————————————————————–|
\n| `material` | Item ID (e.g. `”paper”`, `”clock”`) |
\n| `camera` | Camera\u2011specific options (see below) |
\n| `components` | Optional vanilla data components to apply to the item stack (1.20.5+) |<\/p>\n
\n|—————-|——————————|———————————————————————-|
\n| `resolution` | `{ width, height }` | Output resolution in pixels (e.g. `{ “width”: 256, “height”: 256 }`) |
\n| `color_mode` | string | `”COLOR”`, `”MONOCHROME”`, `”GRAYSCALE”`, `”SEPIA”` |
\n| `dither_mode` | string | `”NONE”`, `”BAYER_2X2″`, `”FLOYD_STEINBERG”`, etc. |
\n| `video_params` | `{ frame_rate, max_frames }` | Video recording parameters |<\/p>\n
\n{
\n “camera”: {
\n “material”: “paper”,
\n “camera”: {
\n “resolution”: { “width”: 128, “height”: 128 },
\n “color_mode”: “COLOR”,
\n “dither_mode”: “NONE”,
\n “video”: { “frame_rate”: 0, “max_frames”: 1 }
\n },
\n “components”: {
\n “minecraft:item_name”: { “text”: “Camera”, “color”: “gold” },
\n “minecraft:max_stack_size”: 1
\n }
\n },
\n “camcorder”: {
\n “material”: “paper”,
\n “camera”: {
\n “resolution”: { “width”: 128, “height”: 128 },
\n “color_mode”: “COLOR”,
\n “dither_mode”: “NONE”,
\n “video”: { “frame_rate”: 20, “max_frames”: 200 }
\n }
\n },
\n “instant”: {
\n “material”: “paper”,
\n “camera”: {
\n “resolution”: { “width”: 256, “height”: 256 },
\n “color_mode”: “SEPIA”,
\n “dither_mode”: “BAYER_4X4”
\n },
\n “components”: {
\n “minecraft:item_name”: { “text”: “Instant Camera”, “italic”: false }
\n }
\n },
\n “polaroid”: {
\n “material”: “paper”,
\n “camera”: {
\n “resolution”: { “width”: 512, “height”: 512 },
\n “color_mode”: “GRAYSCALE”,
\n “dither_mode”: “FLOYD_STEINBERG”
\n },
\n “components”: {
\n “minecraft:item_name”: { “text”: “Polaroid”, “color”: “white” },
\n “minecraft:custom_model_data”: 1
\n }
\n },
\n “pro_camera”: {
\n “material”: “ender_eye”,
\n “camera”: {
\n “resolution”: { “width”: 128, “height”: 128 },
\n “color_mode”: “COLOR”,
\n “dither_mode”: “NONE”,
\n “video”: { “frame_rate”: 30, “max_frames”: 600 }
\n },
\n “components”: {
\n “minecraft:item_name”: { “text”: “Pro Camera”, “color”: “light_purple”, “bold”: true },
\n “minecraft:max_stack_size”: 1,
\n “minecraft:custom_model_data”: 2
\n }
\n },
\n “handycam”: {
\n “material”: “clock”,
\n “camera”: {
\n “resolution”: { “width”: 256, “height”: 256 },
\n “color_mode”: “COLOR”,
\n “dither_mode”: “BAYER_2X2”,
\n “video”: { “frame_rate”: 15, “max_frames”: 450 }
\n },
\n “components”: {
\n “minecraft:item_name”: { “text”: “Handycam”, “color”: “aqua” },
\n “minecraft:max_stack_size”: 1
\n }
\n },
\n “cctv”: {
\n “material”: “observer”,
\n “camera”: {
\n “resolution”: { “width”: 192, “height”: 192 },
\n “color_mode”: “MONOCHROME”,
\n “dither_mode”: “SIERRA”,
\n “video”: { “frame_rate”: 5, “max_frames”: 30000 }
\n },
\n “components”: {
\n “minecraft:item_name”: { “text”: “CCTV Camera”, “color”: “dark_gray” },
\n “minecraft:max_stack_size”: 1
\n }
\n }
\n}
\n“`<\/p>\n
\n\/camera-obscura give camera
\n\/camera-obscura give camcorder
\n\/camera-obscura give instant
\n\/camera-obscura give handycam Notch
\n“`<\/p>\n
\n\/camera-obscura reload
\n“`<\/p>\n
\n– Block models are converted into triangles and stored in a cache (per chunk).
\n– Lighting, ambient occlusion, and fog are computed from the actual world state.
\n– Rendering happens asynchronously on a separate thread pool, no lag for the main game.
\n– After rendering, the image is converted to (a) Minecraft map(s) (or saved as PNG).
\n– **Video recording** captures frames at the configured framerate.<\/p>\n
\n– Higher resolution & SSAA increase CPU usage drastically.
\n– Render distances above 128 may cause issues if chunks are not loaded.
\n– Video recording is CPU\u2011intensive. For high\u2011quality recordings, consider lowering the framerate!<\/p>\n
\n|————————————–|————————————————————————————————-|
\n| Photo doesn’t appear in inventory | Check that `cameraConsumesItem` is `false` or you have the required item (e.g. a map). |
\n| \u201cMissing required item\u201d message | You need the configured `cameraConsumeItem` material in your inventory. |
\n| Very long render times (> 5 seconds) | Reduce `renderDistance`, `ssaa`, or `resolution`. Enable `debug` to see per\u2011frame timings. |
\n| Server crashes with OOM error | Increase server memory (`-Xmx2G` or more). Lower `renderDistance` and `ssaa`. |
\n| Custom Nexo\/ItemsAdder item ignored | Ensure the `camera` section is correctly indented and the mechanic is spelled exactly `camera`. |<\/p>\n