Skip to content
PuniDocs
Open Puni

Developers

The command line, the MCP tools, the scene document and its commands, the HTTP API, and the embed protocol, from the quickstart to the reference.

A scene document: modules, objects, actions, tracks, clips, cameras, shots, audio and the frameone JSON documentmoduleIdactionIdtrackIdtargetIdcameraIdmoduleswhat a thingisinstancesobjects on thestageactionskeys, or aprocedureclipsan action at atimetracksone perobjectcamerasa framingshotsa camera onthe timelineFramewidth × height · fps · durationAudiostart · offset · gain
Objects instance modules; clips place actions on tracks; shots place cameras. One document holds all of it.

Reference

Setup

SetupWhat the command line needs: Node, Chrome for renders, the local renderer for films and Cycles, where credentials live, and what each exit code means.

Scenes

CommandsEvery edit is a command on the document: the thirty-four kinds, atomic batches, command files, and one cloner for many copies.Evaluate and simulateSample a scene at a time for the values of everything in it, and record physics into motion the document keeps.Portable projectsThe .puni.json file: what it contains, how export and import validate it, and how pull and push move a scene between a file and the library.

Integrate

APIThe HTTP routes behind the studio and the command line: projects, transfers, assets, links, devices, agent turns, search and films.The embed protocolThe message API a host page can opt into: connect to the player, inspect controls, set a parameter, seek, play, pause, trigger and reset.WebMCPThe tools Puni's pages register in a browser that supports WebMCP, the loop they follow, and the one thing the browser must have.

Reference

puni authSign a machine in to your library and keep its token.3 commandspuni sceneMake, inspect, edit, evaluate and validate a scene as a file.12 commandspuni projectYour library: list, pull, push, rename, archive, checkpoints, covers and links.18 commandspuni renderDraw a scene file with the studio's own renderer: a PNG, a GLB, a USDZ, or a film.6 commandspuni rendererTalk to the local renderer: Cycles stills from a GLB, and film jobs.6 commandspuni searchFind scenes by name and description, and manage what semantic search knows.6 commandspuni checkpointKeep and restore a scene file with its assets and checksums.2 commandspuni agentDeliver turns to a connected runner, host them on your own machine, and inspect their saved work.7 commandspuni interfaceTurn a Paper layout into an interface object.1 commandpuni studiesThe starting scenes `scene create` can begin from.1 commandpuni runtimeCheck that this build of the command line matches the studio.1 commandpuni contractPrint the command and type contract a scene is made of.1 commandpuni sculptMake a textured object from a picture or a prompt, and split it into named parts.4 commandspuni monoPreviewPuni's own agent runtime, embedded in the command line: a session that can look at a scene before it answers.1 command

Preview marks a command that is still rolling out; its flags may change before it is available everywhere.

MCP tools

  • list_projects
  • search_projects
  • preview_scene_index
  • index_scene_description
  • remove_scene_embedding
  • refresh_scene_search
  • create_project
  • inspect_scene
  • inspect_objects
  • read_contract
  • inspect_module
  • apply_scene_commands
  • stage_commands
  • update_scene
  • upload_asset
  • simulate_scene
  • evaluate_frame
  • puni_render_view
  • puni_compare_reference
  • puni_render_film
  • sculpt_object
  • get_sculpt
  • segment_sculpt

Everything the studio does is a command on a scene document, and every door, the editor, the command line and the agent tools, applies the same commands. This section is that contract, read from the outside.

#Setup

Quickstart gets a scene from the terminal in five commands. Setup covers building the command line, signing in, and checking the runtime.

#Scenes

The scene document is the shape of a saved scene. Commands lists every edit. Evaluate and simulate samples a scene at a time. Portable projects is the file that carries a scene between places.

#Integrate

MCP tools is the agent contract. API lists the HTTP routes and the OpenAPI document. The embed protocol controls a player from a host page. WebMCP is the browser door.

#Reference

Command line has every command with its flags.