FAQ and Troubleshooting

Installing

veduta is not recognised

The installer added its folder to your user PATH, which only new terminals see. Close the terminal and open a new one. In VS Code the extension (0.9.1 or later) gives its terminals the folder itself; with an older one, close every VS Code window and start it again.

Still not found in a new terminal? Check that the folder is there and on the user PATH:

Test-Path "$env:LOCALAPPDATA\Programs\veduta\veduta.exe"
[Environment]::GetEnvironmentVariable('Path', 'User')

If the first line says False, install again. If the second does not list ...\AppData\Local\Programs\veduta, run the installer again: it adds it.

The Lua extension shows no completion

Accept the recommendation to install Lua (sumneko.lua) when the project opens, or install it from the Extensions panel. The project's .luarc.json points it at the API definitions in .veduta/lua/, which every build refreshes to the tool's version.

Writing the game

Missing standard functions

Veduta's Lua is Lua 5.4 without the parts that would break determinism or reach outside the game (io, os, debug, load, goto), and without string.pack, string.unpack and string.dump, which have no use without file access.

Accented letters show as ?

The font covers ASCII, Latin-1 and Windows-1252's extra characters. Other scripts (Greek, Cyrillic, Japanese, emoji) are not in it. Save scripts as UTF-8.

An asset in a folder is not found

Folders under an asset kind's directory work. The asset's name is its file name, whatever the folder: two files of the same name in different folders are an error that names both.

"entity has no field …"

Entities accept only their own fields (x, y, z, visible, model, material, layer, frame, anim, parent, hitbox, color, alpha, body, state). Keep your values in e.state: e.state.speed = 3.

My variables survive scene.load

scene.load resets the entities, not the Lua variables. Reset them where a level starts: in the kind init of an entity the level's scene contains, or next to the scene.load call.

Two sprites never collide

They are at different z. A quad is 0.02 units deep, so sprites overlap only when their z are close. Put them at the same z, or give them hitboxes with depth in the scene file. See 2D Games.

A sprite is invisible

• It faces away: a plane part faces +Y and is edge-on to a 2D camera. Use quad.
• It is behind the camera's range: a 2D camera at z = 100 sees z from −100 to 99.9.
• It is behind an opaque sprite at a larger z, or a translucent sprite on a lower layer.
• visible is false, or its material names a texture that does not exist (veduta inspect scene NAME lists missing assets).

The game behaves differently in a test

Something depends on what is not part of the run: game.draw changing state (it runs once per frame, and tests may draw no frames), or a table iterated with an order that changed because keys were inserted in a different order. Move every change of state into game.update or kinds.

Testing

golden mismatch after a change

The change altered something in the run. Open the scenario's contact sheet under out/runs/ and the trace; if the new behaviour is right, record it with veduta test --update-golden and commit tests/golden/.

A scenario's expectation on position.x == 5 fails at 4.9999995

Positions are float32. Compare with a margin: > 4.99 and < 5.01.

Current limits

These are known and planned, not bugs in your game:

• No sound yet.
• While the debugger is stopped at a breakpoint, the simulator window is not redrawn.
• The simulator window exists on Windows only; Linux and macOS have every headless command.

Getting help

Write to riftbane in the chat on https://veduta.roomve.it with veduta --json doctor output, and a scenario that shows the problem when you can: it replays the same way on any machine. Server errors are on The Veduta Server.