VisualSource v4

API Reference

Public REST API for encoding, decoding, and compiling VisualSource scripts. All endpoints accept and return JSON.

Base URL https://retrostudio-visualsource.onrender.com

Endpoints

POST /encode

Encodes a decoded VisualSource script into the compact base93 format (deflate + base93). The output is ready to paste into RetroStudio.

Request body

Field	Type	Required	Description
`text`	string	required	Raw decoded VS script text (with `\x1a`/`\x1b` separators).
`keep_original`	boolean	optional	Wrap output with `\x1a`/`\x1b` control chars. Defaults to `true`.

Example

json

{
  "text": "EditorCameraPosition0,0\x1a...",
  "keep_original": true
}

Response

{ "output": "\u001a0000000000000004...", "stats": { "input_chars": 142, "compressed_bytes": 89, "output_chars": 124 } }

POST /decode

Decodes a base93-encoded VisualSource script into human-readable block format. Supports versions 1–2 (legacy LZW) and 3+ (deflate).

Request body

Field	Type	Required	Description
`text`	string	required	Base93-encoded VS script string.
`keep_original`	boolean	optional	Preserve `\x1a`/`\x1b` separators in output. Defaults to `true`.

Response

{ "output": "EditorCameraPosition0,0\u001a...", "stats": { "version": "4", "output_chars": 142 } }

POST /toluau

Submits a decoded VS script for compilation to Luau. Returns a job_id immediately. Poll /queue/:job_id for the result.

Request body

Field	Type	Required	Description
`text`	string	required	Decoded VS script text.

Response

{ "job_id": "e3f2a1b4-...", "position": 0 }

GET /queue/:job_id

Polls the status of a Luau compilation job. Keep polling until status is done or error.

URL parameters

Parameter	Type	Description
`job_id`	string	UUID returned by `/toluau`.

Response — pending

{ "job_id": "e3f2a1b4-...", "status": "processing", "position": 0 }

Response — done

{ "job_id": "e3f2a1b4-...", "status": "done", "output": "local ..." }

POST /VS-TO-JSON2

Converts a decoded VS script string into a structured JSON representation of the block tree.

Request body

Field	Type	Required	Description
`text`	string	required	Decoded VS script text.

Response

{ "ok": true, "Editor": { "CameraPosition": "0,0", "CameraZoom": "1" }, "Blocks": [ { "BlockType": "Print", "Name": "Print1", "Inputs": { "Text": { "value_type": "0", "value": "hello", "data_type": "String" } }, "Outputs": {}, "ChildBlocks": [], "ElseChildBlock": null, "VisualPosition": "0,0" } ] }

POST /JSON-TO-VS2

Converts a block tree JSON (as produced by /VS-TO-JSON2) back into a decoded VS script string.

Request body

Field	Type	Required	Description
`Editor`	object	required	Editor metadata (`CameraPosition`, `CameraZoom`).
`Blocks`	array	required	Array of block objects matching the `/VS-TO-JSON2` output schema.

Response

{ "ok": true, "output": "EditorCameraPosition0,0\u001a..." }

POST /parse

Parses a decoded VS script and returns a preview-oriented block structure used by the VS Preview panel.

Request body

Field	Type	Required	Description
`text`	string	required	Decoded VS script text.

Response

{ "ok": true, "blocks": [ { "type": "Print", "name": "Print1", "inputs": {}, "children": [] } ], "editor": { "camera_x": 0, "camera_y": 0, "camera_zoom": 1 } }

GET /findblock?name=:name

Looks up a block by type name and returns its metadata from the block list.

Query parameters

Parameter	Type	Required	Description
`name`	string	required	Block type name (e.g. `Print`, `PlayerAdded`).

Response

{ "found": true, "block_type": "Print", "category": "Output", "visual_name": "Print", "description": "Prints a value to the output.", "inputs": "...", "outputs": "..." }