forma-engine/docs/COMMANDS.json

{
  "transactions": "1–1000 commands apply atomically. Read project_read first. Mutation expectedRevision must match current revision. requestId deduplicates successful retried transactions. On REVISION_CONFLICT reread project before editing.",
  "coordinates": "Y up, meters, radians. Entity transforms local to parent. Reparent preserves local coordinates unless you provide transform. Kinematic move uses world displacement; other move uses local.",
  "commands": {
    "project.rename": "{name}",
    "project.settings": "{background:\"#dedbd2\",ambient:0.85,shadows:true,renderScale:1}",
    "scene.create": "{id?,name,mode?:2d|3d}",
    "scene.configure": "{sceneId?,mode:2d|3d}; default editor view and fallback game camera",
    "scene.activate": "{id}",
    "scene.rename": "{sceneId,name}",
    "node.create": "{name,id?,position?,parentId?,components?,sceneId?} OR {entity:{id,name,parentId:null,enabled:true,transform:{position:[0,0,0],rotation:[0,0,0],scale:[1,1,1]},components:{}}}",
    "node.patch": "{id,patch:{name?,enabled?,transform?,components?},sceneId?}; deep merge, arrays replace, id/parentId immutable here",
    "node.reparent": "{id,parentId:null|string,transform?,sceneId?}",
    "node.delete": "{id,sceneId?}; subtree",
    "node.duplicate": "{id,sceneId?}; subtree and internal references",
    "component.set": "{id,type,value,sceneId?}; replaces component",
    "component.remove": "{id,type,sceneId?}",
    "asset.upsert": "{asset:{id,name,kind:\"model\"|\"geometry\"|\"prefab\"|\"image\",uri?,geometry?,entities?,metadata?,image?}}",
    "asset.delete": "{id}; fails if referenced",
    "script.upsert": "{script:{id,name,source,fields:{speed:{type:\"number\",default:5,label:\"Speed\",min:0,max:30}}}}",
    "prefab.create": "{id,name?,sceneId?}",
    "prefab.instantiate": "{assetId,position?,sceneId?}"
  },
  "components": {
    "sprite": {
      "assetId": "image asset or empty for white quad",
      "frame": 0,
      "size": "optional [width,height], otherwise frame pixels / PPU",
      "color": "#ffffff",
      "alpha": 1,
      "layer": 0,
      "order": 0,
      "flipX": false,
      "flipY": false,
      "sortY": false,
      "lit": false
    },
    "spriteAnimator": {
      "autoplay": "idle",
      "autoStates": false,
      "clips": [
        {
          "name": "idle",
          "frames": [
            0,
            1
          ],
          "fps": 8,
          "loop": true
        }
      ]
    },
    "tilemap": {
      "assetId": "image asset",
      "tileSize": [
        1,
        1
      ],
      "width": 32,
      "height": 18,
      "cells": [
        {
          "x": 0,
          "y": 0,
          "frame": 0,
          "solid": true
        }
      ],
      "collisions": false,
      "layer": 0,
      "order": 0
    },
    "collider2d": {
      "shape": "box | circle | capsule | polygon",
      "size": [
        1,
        1
      ],
      "radius": 0.5,
      "height": 1.8,
      "points": "convex polygon vertices [[x,y],...]",
      "offset": [
        0,
        0
      ],
      "sensor": false,
      "oneWay": false,
      "membership": 1,
      "mask": 65535
    },
    "rigidbody2d": {
      "type": "fixed | dynamic | kinematic",
      "mass": 1,
      "friction": 0.5,
      "restitution": 0,
      "gravityScale": 1,
      "lockRotation": true,
      "ccd": true,
      "requires": "collider2d or colliding tilemap"
    },
    "character2d": {
      "mode": "platformer | topDown",
      "controls": true,
      "speed": 5,
      "jumpSpeed": 8,
      "gravity": 20,
      "autostep": 0.2,
      "requires": "kinematic rigidbody2d + collider2d"
    },
    "joint2d": {
      "type": "fixed | revolute | rope | spring",
      "targetId": "another body2d",
      "anchor": [
        0,
        0
      ],
      "targetAnchor": [
        0,
        0
      ],
      "length": 1,
      "stiffness": 50,
      "damping": 5
    },
    "mesh": {
      "type": "box | sphere | cylinder | icosphere | torus | model | geometry | custom",
      "size": [
        1,
        1,
        1
      ],
      "assetId": "for model/geometry types",
      "geometry": "{positions,indices,normals?,uvs?} for custom type"
    },
    "material": {
      "color": "#91a697",
      "roughness": 0.8,
      "metallic": 0,
      "emissive": 0,
      "override": false
    },
    "collider": {
      "shape": "box | ball | capsule",
      "size": [
        1,
        1,
        1
      ],
      "radius": 0.32,
      "height": 1.8,
      "offset": [
        0,
        0.9,
        0
      ],
      "sensor": false,
      "enabled": true
    },
    "rigidbody": {
      "type": "fixed | dynamic | kinematic",
      "mass": 1,
      "restitution": 0.1
    },
    "camera": {
      "mode": "follow | firstPerson | fixed | imported | 2d",
      "orthoWidth": 20,
      "pixelPerfect": false,
      "pixelsPerUnit": 100,
      "targetId": "subject",
      "offset": [
        0,
        13,
        -10
      ],
      "fov": 0.72,
      "yaw": 0,
      "pitch": 0
    },
    "character": {
      "gravity": 24,
      "autostep": 0.25,
      "requires": "kinematic rigidbody + capsule collider"
    },
    "sign": {
      "text": "Text in the scene",
      "color": "#d7f34b",
      "width": 5
    },
    "light": {
      "color": "#fff1da",
      "intensity": 2
    },
    "animator": {
      "idle": "Idle",
      "run": "Run",
      "attack": "Attack",
      "death": "Death",
      "speed": 1
    },
    "script": {
      "scriptId": "script_rotate",
      "params": {
        "speed": 1
      }
    },
    "data": {
      "customValue": 1,
      "label": "Application-defined properties"
    }
  }
}