World Format

🌐 English · Русский

← Home · Textures →

World Format

The world system

• A world is a single worlds/<name>.json file that owns the whole scene: graphics toggles, the platform, and every object's full transform (position / rotation / scale / color / anchor and, for lights, kind / direction / cone / beams / shape / etc.).
• models/ is a pure mesh library — just <name>.obj files. The world references a mesh by name and supplies its placement (there is no per-model JSON).
• An in-scene editor (toggled with Tab or `) lets you spawn, move, rotate, scale, recolor, and delete objects live, then save back to JSON with F5. See Controls.
• Built-in spawn types: cube, sphere, cylinder, cone, pyramid, ramp (a wedge with a sloped top — great for rolling), flatpicture (a two-sided vertical panel that displays a texture — a poster/billboard, non-colliding), light, camera (a placeable viewpoint — see Cameras & HUD), joint (a physical constraint tying two objects — see Physics; saved in the joints array below, not in objects), plus every mesh in models/.
• Platform shapes: square, rectangle, or circle, with configurable size / color.
• Live graphics toggles: flip shadows (F2), BVH acceleration (F3), the camera headlight (F4), and the floor platform (F6) right in the scene — no need to recreate the world. On a server these sync to every client.

Adding models

Drop a mesh into SampleGame/models/ as <name>.obj (export with vertex normals for smooth shading; Blender does this by default). Models are a pure geometry library — placement (position, rotation, scale, color, anchor, spin) lives in the world.

To place a model, either spawn it live in the editor (G to find it in the spawn list, B to spawn, arrange it, F5 to save), or add an object entry to worlds/<name>.json by hand.

Edit a model or a world JSON and just re-run — no rebuild required.

A world object

{
  "id": 0,
  "type": "mesh",
  "mesh": "monkey",
  "position": { "x": 0.0, "y": 0.0, "z": 0.0 },
  "rotation": { "x": 0.0, "y": 0.0, "z": 0.0 },
  "scale": 1.0,
  "color": "Yellow",
  "anchor": "bottom",
  "rotateSpeed": 1.0,
  "collides": true,
  "gravity": false
}

Common fields

Field	Meaning
type	mesh, cube, sphere, cylinder, cone, pyramid, ramp, flatpicture, light, or camera.
mesh	The models/ file name (without .obj), for type: "mesh".
position	World position in units (Y is the vertical axis).
rotation	Initial rotation in radians.
scale	Uniform scale.
color	A hex string #RRGGBB (or #RRGGBBAA with alpha = object transparency), an R,G,B / R,G,B,A triple, or a .NET ConsoleColor name (e.g. Red). Saved back as hex.
colorFade	Color transparency / paleness, 0–1 (default 0): washes the object's colour toward white, independent of the alpha.
anchor	How the mesh sits at its position: bottom (base on the floor, default), center, or origin (raw OBJ origin).
rotateSpeed	Auto-spin around the vertical axis, in radians per second (0 = static).

Texture fields

See the Textures page for the full system.

Field	Meaning
texture	A textures/ PNG file name (e.g. "brick.png", "" = none/flat colour). Works on every primitive and imported mesh objects. In an online session the PNG bytes stream to peers.
textureScale	UV tiling factor (default 1): 2 tiles the texture 2×2, 0.5 shows half of it.
textureFace	Which face wears the texture (default -1 = all). For a cube, 0–5 select one side (+X, -X, +Y, -Y, +Z, -Z); other faces then show flat colour. Other shapes are a single face.
textureFilter	Sampling: 0 = nearest (default), 1 = bilinear, 2 = mipmapped.

Physics fields

See the Physics page.

Field	Meaning
collides	Is this object solid (effective only when physics.collisionEnabled is true). Default true.
gravity	Is this object pulled down by world gravity (effective only when physics.gravityEnabled is true). Default false.
collider	A mesh's collider shape: "aabb" (world-axis box, default) or "obb" (oriented box that rotates with it).
mass	Impulse-solver mass (default 1); a heavier object is shoved less in a collision.
restitution	Bounciness 0–1; -1 (default) inherits the world's physics.restitution.
friction	Coulomb friction coefficient (default 0.5).
rollingFriction	Rolling-friction resistance (default 0.05).

Light objects

A light object additionally uses: power, lightKind (point / directional / spot / area), direction, coneAngle, beamCount, coneShape (circle / square / triangle), lightSize, and lightSpin. See Rendering & Lighting.

Camera objects

A camera object uses cameraKind (fixed / follow) and, for a Follow camera, followTargetId (the object id it tracks, or -1 = the player body). See Cameras & HUD.

The top-level physics block

"physics": { "gravityEnabled": false, "gravityStrength": 9.8, "collisionEnabled": true, "restitution": 0.0 }

restitution is the world's default Bounce (0–1); individual objects can override it. The world file also carries a top-level graphics block (Shadows / BVH / ExtraLight / DisableCameraLight / Renderer), a platform block, and a joints array (below).

The top-level joints array

Joints live in their own top-level array (not in objects) — each ties two objects together, or an object to the fixed world. Spawn one in the editor (the joint spawn type) or add an entry by hand. See the Physics page.

"joints": [
  {
    "id": 5, "kind": "hinge", "bodyA": 1, "bodyB": -1,
    "anchorA": { "x": 0, "y": 0, "z": 0 }, "anchorB": { "x": 0, "y": 2, "z": 0 },
    "axis": { "x": 0, "y": 1, "z": 0 },
    "limitEnabled": true, "lowerLimit": -1.0, "upperLimit": 1.0,
    "motorEnabled": false, "motorTargetSpeed": 0.0, "maxMotorTorque": 0.0
  }
]

Field	Meaning
kind	ballsocket, hinge, or distance.
bodyA / bodyB	The two object ids to connect; -1 = the fixed world (a static anchor point). Any object works — a non-physical or static side (a light, a prop, or the platform) acts as a draggable fixed/kinematic anchor.
anchorA / anchorB	The anchor in each body's local frame (or a world position when that id is -1).
axis	(hinge) the shared rotation axis.
limitEnabled / lowerLimit / upperLimit	(hinge) an angle-stop range, in radians.
motorEnabled / motorTargetSpeed / maxMotorTorque	(hinge) a torque-limited drive toward a target angular speed.
restLength	(distance) the target separation between the anchors.
springEnabled / frequency / dampingRatio	(distance) a soft spring (frequency in Hz + damping ratio) instead of a rigid rod.
collide	Do the two connected bodies also collide with each other? Default false. Turn on for surface/edge-anchored joints (e.g. a real chain whose links should bump, not fold through).