v0.70.1 From The Terminal

Floptle has a command line. You can now find out whether a project loads, whether it runs, what it looks like and what is inside it — and change it correctly — without opening the editor. That means your CI can do those things, and so can an AI assistant working in your project folder alongside you.

Find out whether it works, without opening it

floptle check                    # does everything still load?
floptle run --frames 120         # play it for two seconds and report what raised

check loads every scene, prefab, effect and material and reports every reference that does not resolve — a parent pointing at the wrong node, a material naming a texture that is not there, a node carrying a script with no file behind it. A .ron file that parses is not a scene that works, and until now the only thing that could tell you the difference was opening the project.

run is the bigger gap closed. It plays the project for a fixed number of frames with no window at all — the real scripts, the real physics — and reports every warning, error and print with its file and line, exiting non-zero if anything raised. Pointed at a real game it found a script indexing a nil value on the first try.

Both are safe to put in a build pipeline. Neither needs a display.

See what it looks like

floptle shot --out look.png
floptle shot --scene arena --camera "Chase Cam" --size 1920x1080

One frame through the scene's active camera, straight to a PNG. It goes through the same rendering path the editor's own Game view uses, and it applies the project's post-processing — bloom, vignette, ambient occlusion, posterise, colour grading, depth of field, your own post shaders, and the retro presentation at its own resolution. What lands in the file is what the editor would show you.

Read a project, and change it correctly

floptle inspect                          # what this project is
floptle inspect --scene first            # its nodes, as a tree
floptle inspect --select Player --json   # one node's whole document
floptle exec fix.lua                     # change it, through the editor's own API

inspect reads the files, which is what you want when you are about to edit them, and it builds the hierarchy the way the engine does rather than the way the file happens to be ordered.

exec runs a Lua file against the project through the same scripting API the editor's own extensions use — scene.find, scene.setPos, scene.add, ed.saveScene(). Use it instead of hand-editing scene files when the change is structural: node ids, parent links and defaults come out right because the same code does it. Nothing is written unless the script calls ed.saveScene(), and if it changes something and forgets, the run tells you rather than losing it.

Look up what a script can call

floptle api setSprite
floptle api "collision"      # search the descriptions too

Every name a script can reach, with what it does and an example, searchable by part of a name or by a word from the description. It exits non-zero when nothing matches, so floptle api node:doesNotExist answers a yes/no question.

Every command describes itself

floptle help --json

The whole surface as one document: every command, its arguments, the values each one accepts, what comes back, what each exit code means, and two flags worth knowing before you run anything in a container or over SSH — whether the command needs a display, and whether it will write into your project.

It is generated from the same table the parser is built from, so it cannot describe a command that does not exist, and a command cannot exist without appearing in it.

Every flag that worked before still works. --export, --new, --migrate, --play, --version and the rest are unchanged; the verbs sit alongside them. If you drive Floptle from a script today, nothing you wrote has to change.

New projects come with a guide

floptle new now writes an AGENTS.md at the project root — a short page telling an AI assistant which commands exist, what the project's folders are for, and two things about scene files that otherwise cost an afternoon. It is written once and never touched again, so edit or delete it freely.

A lit sprite draws one frame, not the whole sheet

With 2D lighting in the scene, a ▫ Sprite on a spritesheet drew the correct frame and a squashed, stretched copy of the entire sheet on top of it — usually crowded into one corner, wherever that sheet's filled cells happened to land. Changing the frame moved the sprite underneath and left the ghost where it was. Turning the lights off made it disappear.

2D lighting works by correcting the frame that was already drawn: it measures the difference between what is on screen and what the lights say should be, and adds that difference back. It was measuring against the whole sheet rather than the one frame, so the difference it added back was the rest of the sheet.

The same reading decided which pixels of a sprite block light, so a sprite's shadow was cast by the shape of the whole sheet rather than by the frame you can see. Both are fixed together.

This is the other half of the spritesheet fix in v0.69.1. If you upgraded to that one and a stretched sheet was still sitting over your sprites, this is what was left. Tilemaps were never affected, and neither is anything in a scene without 2D lights.

What isn't in it

There is no floptle serve yet — the dedicated server still has its own command line. check reports problems but does not fix them. And --bake-gi still opens the editor to do its work despite what its help says.

floptle shot needs a Vulkan, Metal or DirectX 12 adapter. On a machine with only OpenGL it cannot build the renderer, and it now says so and stops instead of looking like a crash. Everything else on this page works with no graphics adapter at all.

Upgrading

Nothing to do. Scenes, projects, clips and scripts are unchanged, and every existing flag behaves as it did. Existing projects do not get an AGENTS.md; if you want one, floptle help --json is the page it would point at anyway.