Cairn

    Command reference

    Every command the editor takes, with its parameters in brackets. This page is generated from the command processor: do not edit it by hand. After adding or changing a command, run the unit tests with CAIRN_UPDATE_DOCS=1 to rewrite it.

    • help: Lists every command.
    • scene.info: The scene's name, file, entity count, whether it has unsaved changes, and the play state.
    • scene.get (format: "yaml" (default) or "json"): The whole scene, in the form scene files have.
    • scene.set_name (name): Renames the scene. Not an undo step.
    • scene.settings (data: optional object of render settings to change): Reads the render settings (Exposure, BloomIntensity, BloomThreshold, AntiAliasing, AmbientOcclusion, AmbientOcclusionRadius, AmbientOcclusionIntensity) and changes the ones given in data.
    • scene.save (path: optional file to save to, inside the project or anywhere on disk): Saves the scene to its file, or to path, which then becomes its file.
    • scene.open (path: a scene file, inside the project or anywhere on disk): Replaces the scene with a scene file. Unsaved changes and the undo history are lost.
    • entity.list: Every entity in hierarchy order, with its ID, name, parent and the names of its components.
    • entity.get (entity; format: "json" (default) or "yaml"): Everything about one entity: name, tag, layer, transform and every component with its values.
    • entity.find (name, tag, component: any of them): The entities that match every filter given, in hierarchy order.
    • entity.create (name; parent: optional entity; mesh: optional "Cube", "Sphere", "Plane" or a mesh asset ID; data: optional values as in entity.update): Creates an entity and selects it. Returns its ID.
    • entity.update (entity; data: object of values to change): Changes an entity. data has the shape entity.get returns: {"Name": ..., "Transform": {"Translation": [x, y, z]}, "PointLight": {"Range": 5}}. Only what is given changes. A component that is not there yet is added, and null removes one: {"PointLight": null}. A list (Materials, Scripts) is replaced whole.
    • entity.delete (entity, or entities: a list): Deletes entities and everything under them.
    • entity.duplicate (entity, or entities: a list): Copies entities, with everything under them, next to the originals. Returns the IDs of the copies and selects them.
    • prefab.create (entity: the top entity to make the prefab from; path: where to save it, ending in .cairnprefab): Saves an entity and everything under it as a prefab file, and makes them an instance of it. A prefab is placed with prefab.instantiate, or from a script with Scene.Instantiate. A scene stores an instance as what it changed, so a later change to the prefab reaches every instance that did not change the same thing.
    • prefab.instantiate (prefab: its ID or path; parent: optional entity; data: optional values for the instance's top entity, as in entity.update): Places an instance of a prefab in the scene and selects it. Returns the ID of its top entity. Give its position in data: {"Transform": {"Translation": [x, y, z]}}.
    • prefab.overrides (entity: any entity of the instance): What an instance changed from its prefab: for each of its entities, the values that differ, in the shape entity.update takes. A component set to null was taken off. removed lists the prefab's entities this instance deleted.
    • prefab.apply (entity: any entity of the instance): Writes an instance back to its prefab file: what it changed, added and deleted becomes the prefab. Every other instance follows, except where it has changes of its own. The instance's own position and rotation stay its own. Instances in scenes that are not open follow when those scenes are next opened.
    • prefab.revert (entity: an entity of the instance; instance: optional, true reverts every entity of the instance): Sets an entity back to what its prefab says, dropping what the instance changed. The instance's top entity keeps its position and rotation. Entities the instance deleted do not come back, and ones it added stay.
    • prefab.unpack (entity: any entity of the instance): Cuts an instance's tie to its prefab. Its entities stay as they are and become ordinary entities, which changes to the prefab no longer reach.
    • entity.set_parent (entity; parent: an entity, or null for the root; index: optional position among the new siblings): Moves an entity in the hierarchy. Its local transform is kept.
    • selection.get: The IDs of the selected entities. The last one is the primary selection, which the inspector shows.
    • selection.set (entities: a list, empty to select nothing): Selects entities.
    • edit.undo: Undoes the last change. Returns what was undone.
    • edit.redo: Redoes the last undone change. Returns what was redone.
    • edit.history: What undo and redo would do next, if anything.
    • play.start: Enters play mode: the scene's scripts start running. Everything they change is thrown away by play.stop.
    • play.stop: Leaves play mode and puts the scene back as it was at play.start.
    • play.pause (paused: true (default) or false): Pauses or resumes play mode.
    • play.run (frames, or seconds): Runs the game for a number of frames, or seconds of game time, at 60 frames per second, and returns what was logged meanwhile. It does not wait for real time to pass, so a run always gives the same result. Enters play mode first if needed, and stays in it.
    • lua.run (code): Runs Lua code with the scripting API, for looking into or poking at the running game. Use print to get values back: they come back in the log.
    • input.set (binding: a key, button or stick such as "Space", "Mouse Left" or "Gamepad LeftX"; value: true or false, or a number from -1 to 1 for a stick): Presses or lets go of a key or button for the running game, as a player would. It stays that way until set again, so send play.run to let frames pass, then set it back.
    • input.release_all: Lets go of every key and button.
    • input.get_map: The input map: each action with the keys, buttons and sticks bound to it. A minus in front of a name means it pushes the action the other way.
    • input.set_action (name; bindings: a list such as ["Space", "Gamepad A"] or ["D", "-A", "Gamepad LeftX"]. An empty list removes the action): Adds an action to the project's input map, or changes or removes one. Scripts read it with Input.IsDown(name), Input.WasPressed(name) and Input.GetValue(name).
    • log.get (since: optional sequence number; level: optional "trace", "info", "warn" or "error"): Log lines after the given sequence number, at the given level or above. Each line has a sequence number: pass the last one seen as since to get only what is new.
    • log.clear: Forgets the log lines kept for log.get.
    • asset.list (type: optional "Model", "Mesh", "Material", "Texture", "Scene", "Script", "Audio", "Prefab", "Skeleton", "Animation" or "Animator"): The project's assets, sorted by path, each with the ID to refer to it by. The meshes, materials and textures inside a model are listed with the model's path and a part such as "Mesh/0".
    • asset.refresh: Looks at the project's files again. Needed after files were added or changed from outside the editor.
    • asset.import (source: a file anywhere on disk; path: where to put it inside the project): Copies a file into the project: a model (.gltf, .glb), a texture (.png, .jpg, .hdr), a script (.lua, or .ts in a TypeScript project) or a sound (.wav, .mp3, .flac). A .gltf's separate .bin and image files must be imported too, next to it. Returns the new asset's ID, and for a model its parts.
    • asset.move (asset: its ID or path; path: where it goes inside the project, with its file name): Moves or renames an asset's file, with the .meta file that holds its ID, so everything that uses the asset still finds it. The kind of file cannot change. Not an undo step.
    • asset.delete (asset: its ID or path): Deletes an asset's file and its .meta file, for good. What used it then has nothing there: a missing material draws as the default one, a missing texture as white, and a scene with an instance of a missing prefab does not load. Not an undo step.
    • material.create (path: where to save it, ending in .cairnmat; data: optional values): Creates a material file. data may set BaseColor [r, g, b, a], Metallic, Roughness, Emissive [r, g, b], NormalScale, OcclusionStrength, AlphaMode ("Opaque", "Mask", "Blend"), AlphaCutoff, DoubleSided, and the textures BaseColorTexture, MetallicRoughnessTexture, NormalTexture, OcclusionTexture and EmissiveTexture as texture asset IDs. Returns the material's ID, for a MeshRenderer's Materials list.
    • animator.write (path: where to save it, ending in .cairnanimator; data: the animator): Creates an animator controller file or replaces it. data is {"Parameters": {"Speed": 0, "Grounded": true}, "Start": "Idle", "States": [{"Name": "Idle", "Clip": "Assets/Models/Hero.gltf#Animation/0", "Loop": true, "Speed": 1, "Events": [{"Time": 0.4, "Function": "OnFootstep"}]}], "Transitions": [{"From": "Idle", "To": "Walk", "When": "Speed > 0.1 and Grounded", "AtEnd": false, "Fade": 0.2}]}. From may be "Any". An event calls that function on the entity's scripts. Returns the animator's ID, for an Animator component's Controller. A running game picks the change up at once.
    • animator.get (animator: its ID or path): An animator controller file's contents, in the shape animator.write takes.
    • material.get (material: its ID or path): A material file's values.
    • material.update (material: its ID or path; data: values to change): Changes a material file. Takes the same values as material.create, and changes only what is given. null removes a texture. Everything that uses the material shows the change.
    • script.write (path: where to save it, ending in .lua, or .ts in a TypeScript project; text: the script's source): Creates a script file or replaces its text. In a TypeScript project every script is compiled to Lua before the answer, and what does not compile comes back under errors while the game keeps the Lua that compiled last. Returns the script's ID, for an entity's Scripts list. Docs/docs/scripting/api.mdx says what a script can call. A running game picks the new code up at once.
    • script.read (script: its ID or path): A script file's text.
    • script.fields (script: its ID or path): The fields a script exposes, with their default values. These are what an entity's Scripts entry can set under Fields.
    • editor.quit: Closes the editor. Unsaved changes are lost, so send scene.save first if they matter.
    • project.info: The open project's name, file, directory and start scene.
    • project.set_audio (master, music, sfx: volumes from 0 to 1; music_low_pass, sfx_low_pass: a cutoff in hertz, 0 for none; music_reverb, sfx_reverb: from 0 to 1; master_muted, music_muted, sfx_muted: true or false. Each optional): Sets how each audio bus starts out: its volume, the low-pass and reverb of Music and Sfx, and whether a bus is muted. Every sound plays on Music or Sfx, and both go through Master. Takes effect at once.
    • project.set_physics (gravity: [x, y, z]; layers: names for the entity layers, the first for layer 0; ignored_layer_pairs: a list of [layer, layer], each a name or a number. All optional, and each replaces what was there): Sets the project's gravity, layer names and which layers pass through each other. An entity's layer is its 'Layer' number. Takes effect at once, also in play mode.
    • project.create (directory: where to make it, which must be empty or not exist yet; name; language: optional "lua" (the default) or "typescript", what its scripts are written in, fixed for good): Creates a project: a project file, and a start scene with a camera, a sun and a sky. Returns the project file. Send project.open to work in it.
    • project.open (path: a .cairnproject file): Closes the open project and opens another, with its start scene. Unsaved changes are lost.
    • project.set_start_scene (scene: its ID or path): Sets the scene the game opens first.
    • template.list: The project templates that come with the editor: starting points with scripts, materials and a level. Each has an id for template.apply, a name, a description and the language of its scripts ("lua" or "typescript"), which must be the project's.
    • template.apply (template: an id from template.list): Fills the open project from a template: copies the template's files in, builds its scene and saves it. Meant for a project that was just made with project.create and opened. Files the project has already are kept. Not an undo step.
    • project.set_app (name: what the game is called; version: text such as "1.2.0"; icon: a texture's ID or path, or null for none. All optional): Sets the game's name, the version an exported game carries and the icon it has. On macOS the icon must be a square PNG of 512 or 1024 pixels.
    • export (output: the directory to put the game in, outside the project; platform: optional "windows", "macos" or "linux", this machine's by default; runtime: optional path of a Cairn-Runtime built for that platform, needed for any platform but this machine's; moltenvk: optional path of libMoltenVK.dylib for a macOS game): Makes the game: the runtime program under the project's name with every file of the project in one pack (Game.cairnpak). A folder on Windows and Linux, a .app on macOS. It has no editor in it. Exports what is on disk, so send scene.save first. Returns the game, its program and any warnings.
    • scene.new (path: where to save it, ending in .cairnscene; name: optional): Creates an empty scene file in the project and opens it. Unsaved changes to the open scene are lost.
    • screenshot (path: the PNG file to write; width, height: optional, 1280 by 720 by default; camera: optional entity with a Camera; position and look_at: optional [x, y, z] for a free view; fov: optional degrees for a free view; physics: optional, true draws the outlines of colliders, characters and joints): Renders the scene to a PNG. With nothing else given it is the game's view, through the scene's primary camera. camera picks another camera in the scene. position and look_at give a view from anywhere, which is the way to check on something from several sides. Works in and out of play mode.