Skip to content

Scene Format


The .dump file stores a header containing width, height, spp, render time, and the actual dump which is three "doubles" per pixel. Doubles are Double-precision floating-point format (sometimes called FP64 or float64).

Old Dump Format

GZIP stream of header + dump stored in column major order

New Dump Format

0x44 0x55 0x4D 0x50 <1 as int> <header> <dump compressed with fpc magic>

<width int> <height int> <spp int> <render time in millis long>


The octree file is GZIP compressed and contains a version integer, block palette, world octree, water octree, grass tinting, foliage tinting, and water tinting data. The first 4 bytes are a version number and currently must be between v3 and v6. v3-v4 octrees are currently converted to v5 for loading as data nodes (only used for water and lava) were replaced by new per-variant types.

Octree Format

<version int> <block palette data> <world octree data> <water octree data> <grass tinting data> <foliage tinting data> <water tinting data if version >= 4>

The section of code.

Block Palette Data

Stores NBT tags for each block.

<version int == 4> <number of block types> <Serialized NBT tags for each block in order>

World and water Octree Data

"octree is pretty complex lol"

"The octree itself is something like storing it depth first with 0xFFFF FFFF as a node and the type if it is a leaf."

World/Tint Textures

Stores tint colors for grass, foliage, and water as WorldTexture.

<number of tiles (chunks)> for each tile: <chunk x coordinate int> <chunk y coordinate int> <chunk texture in x major order, rgb as floats in linear color space>


The .emittergrid is only generated if Emitter Sampling Strategy is set to One or All. Is also GZIP compressed.

  • Version 0 - <version as int> <grid size as int> <cell size as int> for each emitter position <positions as ints, -x, -y, -z corner, +0.5 to get center> for each grid <number of emitters in grid, index of emitters in positions array>

  • Version 1 -<version as int> <cell size as int> <grid offset x> <grid size x> <grid offset y> ...

  • Version 2 - <x,y,z center float, radius as float> for emitter position

Scene Description Format (SDF)

Most of the settings in Chunky scenes are stored in Scene Description files using a JSON-based file format. This page documents the SDF file format. The documentation is currently incomplete, and may lag behind the current Chunky version as new versions are released. Check the version history at the end of this page to see the latest updates made to the SDF documentation.

SDF JSON files are stored in the scene directory and the filename is based on the scene name with .json appended. For example, the JSON file for a scene named MyScene would be MyScene.json.



Key Value range Default value Description
sdfVersion Integer 9 Scene Description Format (SDF) version
name String Scene name
width Integer 400 Canvas width
height Integer 400 Canvas height
yClipMin Integer Clipping world when loading into scene
yClipMax Integer Clipping world when loading into scene
yMin Integer Slicing map view (impacts octree offset)
yMax Integer Slicing map view (impacts octree offset)
exposure Number 1 Camera exposure
postprocess {"NONE", “TONEMAP2”, "GAMMA", "TONEMAP3", "TONEMAP1"} “GAMMA” Tonemapping operator
outputMode {"PNG", "TIFF_32", “PFM”} PNG Image output mode
renderTime Number Current cumulative rendering time
spp Integer Current samples per pixel (SPP)
sppTarget Integer 1000 Render SPP target
rayDepth Integer 5 Ray recursion depth
pathTrace Boolean false Rendering mode (true = path tracing, false = preview)
dumpFrequency Integer 500 How often the current render state is saved (samples per state save)
saveSnapshots Boolean false Whether a snapshot image is saved for each render dump
emittersEnabled Boolean false Whether emitters should emit light or not
emitterIntensity Number 13.0 Controls intensity of emitters
sunEnabled Boolean true Whether the sun should emit light or not
stillWater Boolean false Whether water should be still or wavy
waterOpacity Number {0 to 1} 0.42 Opacity of water
waterVisibility Number 9.0 Distance rays can travel in water in blocks
useCustomWaterColor Boolean false Toggle between biome tinted water and custom water color
waterColor RGB Object See below
fogColor RGB Object See below
fastFog Boolean true Faster fog algorithm
biomeColorsEnabled Boolean true Enable biome tint
transparentSky Boolean false Treat sky as transparent
fogDensity Number 0.0 Fog density
skyFogDensity Number {0 to 1} 1.0 Controls the amount fog blends into the sky
waterWorldEnabled Boolean false Enable water world
waterWorldHeight Number 63.0 Controls height of water world
waterWorldHeightOffsetEnabled Boolean true Applies Minecraft water offset
waterWorldClipEnabled Boolean true
renderActors Boolean true
world World Object See below
camera Camera Object See below
sun Sun Object See below
sky Sky Object See below
cameraPresets Array of Camera Preset Objects See below
materials Material Array Object See below
chunkList Array of integer arrays Chunks in the scene
entities Array of Entity Objects Static entities in the scene, e.g. paintings
actors Array of Actor Objects Posable entities such as players.
entityLoadingPreferences entityLoadingPreferences Object See below
octreeImplementation {“PACKED”, “NODE”, “BIGPACKED”} “PACKED” Octree implementation to use
bvhImplementation {“SAH_MA”, “SAH”, “MIDPOINT”} “SAH_MA” BVH implementation to use
emitterSamplingStrategy {“NONE”, “ONE”, “ALL”} “NONE” Enables NEE for emitters for one or all per bounce
preventNormalEmitterWithSampling Boolean true Attempts to prevent normal emitters and just use NEE
animationTime Number 0.0
renderer {“PathTracingRenderer”} “PathTracingRenderer” Change renderer used for path tracing
previewRenderer {“PreviewRenderer”} “PreviewRenderer” Change renderer used for previews
additionalData {} {} Unknown

RGB Object

Key Value range
red Number {0 to 1}
green Number {0 to 1}
blue Number {0 to 1}

World Object

Key Value range
path String
dimension Integer {0 to 2}

Camera Object

Key Value range Default value Description
name String “camera 1”
position XYZ Object See below
orientation Direction Object See below
fov Number 70.0 Field of View
dof Number "Infinity" Depth of Field, also accepts numbers like "0.0"
focalOffset Number 2.0 Distance to target
shift XY Object See XYZ object

XYZ Object

Note - XY Object is a XYZ Object just without the Z component.

Key Value range
x Number
y Number
z Number

Direction Object

Key Value range Description
roll Number In radians
pitch Number In radians
yaw Number In radians

Sun Object

Key Value range Default value Description
altitude Number {0 to PI/2} 1.0471975511965976 The direction to the sun above the horizon (60 degrees in radians)
azimuth Number {0 to 2PI} 1.2566370614359172 The direction to the sun measured from north (-72 degrees in radians)
intensity Number 1.25 Sunlight scaling factor
color RGB Object See above
drawTexture boolean true Whether to draw the resource pack texture for the sun or not

Sky Object

Key Value range Default value Description
skyYaw Number {0 to 2PI} 0.0 Offset angle for the sky map in radians
skyMirrored Boolean true Enables mirroring of the skymap at the horizon (use when the vertical skymap angle is 90 degrees)
skyLight Number 1.0 Sky light scaling factor
horizonOffset Number 0.0 Offset the horizon to simulate a curved earth. This helps hiding the horizon below distant objects.
cloudsEnabled Boolean false Enable clouds
cloudSize Number 64.0 Scale cloud map
cloudOffset XYZ Object See above
gradient Array of Gradient Objects See below
color “RGB” Object Not really an RGB object.. but kinda?
simulatedSky {"Preetham", “Nishita”} "Preetham" Select method of rendering a simulated sky
skyCacheResolution Integer 128 Internal resolution to be used for simulated sky, is interpolated
skymap String Path to skymap
skybox Array of six Strings Array of six paths to skybox images

Gradient Object

Key Value range
rgb String (RGB HEX)
pos Number

Camera Preset Object

Key Value range Default value Description
"camera object: name" Camera Object "camera name" is the value of the name field

Material Array Object

Key Value range Default value Description
"block/entity name" Material Object Ie "minecraft:acacia_log": {...}

Material Object

Key Value range Default value Description
emittance Number {0+} How much light the material emits
specular Number {0 to 1} Specular reflection coefficient
roughness Number {0 to 1} Blurriness of reflection
ior Number Index of refraction
metalness Number {0 to 1} Percentage of rays tinted by material color (complex fresnel)

Entity Object

Key Value range Default value Description
kind String Minecraft entity name
position XYZ Object See above
rotation Integer Entity rotation
design Banner Design Object See below
text Array of four Text Objects See below
direction Integer Entity rotation
material {“oak”, "dark_oak"} TODO Sign Material
art String Minecraft art ID
angle Number art angle? Legit just at n90 degrees.
placement Integer Head placement?
skin String Head texture URL
Key Value range Default value Description
base Integer Banner base
patterns Arrange of Patterns Object See below

Patterns Object

Key Value range Default value Description
pattern {"b", "bs", "ts", "ls", "rs", "cs", "ms", "drs", "dls", "ss", "cr", "sc", "ld", "rud", "lud", "rd", "vh", "vhr", "hh", "hhb", "bl", "br", "tl", "tr", "bt", "tt", "bts", "tts", "mc", "mr", "bo", "cbo", "bri", "gra", "gru", "cre", "sku", "flo", "moj", "glb", "pig"} Banner pattern code
color Integer

Text Object

Key Value range
text String
color Integer

Actor Object

Key Value range Default value Description
kind String Minecraft posable name
position XYZ Object See above
scale Number Scale actor
headScale Number Scale actor head
showArms Boolean Hide/show actor arms
gear Array of Gear Objects See below
pose Pose Object See below
invisible Boolean If actor is invisible
noBasePlate Boolean If armour_stand base plate is visible

Gear Object

Key Value range Default value Description
head ID_Skin Object “head”
{“feet”, “legs”, “chest”} “id”: “...” Minecraft item ID

ID_Skin Object

Key Value range Default value Description
id String “minecraft:player_head”
skin String URL for skin texture

Pose Object

Key Value range Default value Description
all Array of three Numbers Array of parts Roll, Pitch, and Yaw
head Array of three Numbers Array of parts Roll, Pitch, and Yaw
chest Array of three Numbers Array of parts Roll, Pitch, and Yaw
leftArm Array of three Numbers Array of parts Roll, Pitch, and Yaw
rightArm Array of three Numbers Array of parts Roll, Pitch, and Yaw
leftLeg Array of three Numbers Array of parts Roll, Pitch, and Yaw
rightLeg Array of three Numbers Array of parts Roll, Pitch, and Yaw

entityLoadingPreferences Object

Key Value range Default value Description
se.llbit.chunky.entity.Book true Whether to load book entities
se.llbit.chunky.entity.ArmorStand true Whether to load armor stand entities
se.llbit.chunky.entity.PaintingEntity true Whether to load painting entities
se.llbit.chunky.entity.PlayerEntity true Whether to load player entities
other true Whether to load “other” entities


A simple way to process scene files is by using a scripting language like Python. For example, here is a Python script that generates individual scenes for each chunk in a square grid of chunks. The script uses an original scene as template for the new scenes.

import json
import os.path

original_scene = 'D:\Users\Jesper\.chunky\scenes\shore-sun.json'
scene_dir = os.path.abspath(os.path.join(original_scene, os.pardir))

with open(original_scene, 'r') as f:
    scene = json.load(f)

for x in range(-10, 1):
    for z in range(110, 119):
        scene_name = 'chunk_%dx_%dz' % (x, z)
        scene['name'] = scene_name
        scene['chunkList'] = [ [ x, z ] ]
        scene['spp'] = 0
        scene['renderTime'] = 0
        new_scene = os.path.join(scene_dir, scene_name + '.json')
        print('Writing scene file %s' % new_scene)
        with open(new_scene, 'w') as f:
            json.dump(scene, f)

Version History

  • Version 2 (Chunky 1.2.0 to 1.2.3)
  • Version 3 (Chunky 1.3-alpha1 to 1.3.3)
  • Version 4 (Chunky 1.3.4)
    • removed clearWater (Boolean)
    • added waterOpacity (Number)
    • added waterVisibility (Number)
    • added waterColor (RGB Object)
    • added useCustomWaterColor (Boolean)
  • Version 5 (Chunky 1.3.5-alpha5)
    • removed atmosphereEnabled (Boolean)
    • removed volumetricFogEnabled (Boolean)
    • added fogDensity (Number)
    • added fogColor (RGB Object)
    • added fastFog (Boolean)
  • Version 6 (Chunky 1.3.5-alpha5)
    • Changed postprocess from Integer to Enum
    • Added outputMode (Enum)
  • Version 7 (Chunky 1.3.8)
    • Added renderActors (Boolean)
    • Added actors (Array of Entity Objects)
  • Version 8 (Chunky 1.4.3)
    • Added materials (material properties)
  • Version 9 (Chunky 1.4.4)
    • Changed entity pose format.
    • Added entity armor items.