Skip to content

Sets & Locations

A set is a directory under sets/ bundling three files:

sets/apartment_complex/
├── set.blend      # the Blender scene (large; via Git LFS)
├── set.json       # metadata: locations, anchors, camera points, actor_scale
└── __init__.py    # loads the set, exposes locations as importable attributes

The object model

ProductionSet                 a set.blend + set.json package
└── Location          e.g.  canal_bridge
    ├── Sublocation   e.g.  Tree1            (attribute = its name; spaces/dashes → _)
    │   └── Shot      e.g.  A1               (an anchor: position + theta + radius)
    └── CameraPoint   e.g.  Camera_Point_1   (a fixed world camera position)
  • A Shot is an anchor and a context manager: with canal_bridge.Tree1.A1 as shot:.
  • A Location is also a context manager: with canal_bridge as shot:.
  • RawAnchor(x, y, z, theta=0) wraps a raw tuple so at=(x, y, z) works anywhere.
  • bare_scene is a stand-in location with no .blend (for isolating actors/cameras/lights).

set.json schema

{
  "actor_scale": 1.5,            // multiplies blocking offsets, camera R, light distances
  "actor_motion_scale": 2.0,     // locomotion distance scaling
  "locations": {
    "canal_bridge": {
      "name": "Canal Bridge",
      "sublocations": {
        "A": {
          "name": "Tree1",       // → attribute canal_bridge.Tree1
          "shots": {
            "A1": { "position": {"x": -97, "y": -107, "z": 0.2}, "theta": -40,
                    "radius": {"s1": 4, "s2": 4} }
          }
        }
      },
      "Camera_Points": { "CP1": { "name": "Camera_Point_1", "position": {…} } }
    }
  }
}

Attribute names come from name, not the key

Sublocation D named "Canal_Bridge1-North_End" is reached as canal_bridge.Canal_Bridge1_North_End (dashes/spaces/dots → _).

actor_scale is the magic knob

It multiplies blocking gaps, camera R, and light distances — so set units don't have to be metric. apartment_complex uses 1.5.

Loading mechanics

set.json is read immediately, but set.blend is only linked into the scene when the shot opens (ProductionSet.load() — called by ShotContext.__enter__). The default Cube/Camera/Light are removed first.

Adding a set or an actor

  1. Drop set.blend + set.json in sets/my_set/.
  2. Add sets/my_set/__init__.py mirroring apartment_complex/__init__.py.
  3. Define locations/sublocations/shots/camera points in set.json.
  1. Drop a Mixamo rig FBX at assets/characters/my_actor.fbx.
  2. Add an entry under my_actor in assets/character_descriptions.json (description, voice, instructions).
  3. Import it: from dsl.actors import my_actor. Animations are shared — no per-actor files.

Explore the Features