Glossary¶

The terms the tutorial and reference introduce, in alphabetical order. In the tutorial, the first use of most of them links back here.

API revision¶: The "api_revision": 2 line in meta.json. It must accompany "api": "vs2". See Your first game.
Asset pack¶: The images a game loads, compiled into a ROM. It defaults to your own game’s folder, so you rarely name it. Each pack has its own budget of image strips. Sounds are not part of it: they stay as MP3s that the base station plays.
Back button¶: The Y or BACK button. By default it pops the current scene; set back_button to False to use those buttons in play.
Budget¶: A fixed limit on how many layers, sprites, tilemaps and image strips a game may use. Exceeding one raises an error the first time the scene is entered. See Budgets and real hardware.
Build¶: Scene.build(). It runs once each time a scene is entered and creates everything the scene will draw. When it returns, the scene is sealed.
Cell¶: One byte in a tilemap’s grid. It holds a tile index, or vs2.EMPTY_TILE for “draw nothing”.
Census¶: The per-layer breakdown in a ResourceLimitError message, such as (world: 62, hud: 39). It shows which layer is over budget.
Column¶: One slice of the display: the colour of all 54 LEDs at a single angle. The renderer is asked for 256 of them per rotation.
Console¶: The real Ventilastation machine, as opposed to the emulator.
CP437¶: The default glyph mapping, where a character’s frame is ord(ch). Full font strips such as steel8x8.png use it.
Depth¶: What Y means on a vs2.TUNNEL layer: 0 at the rim, 255 at the centre. Objects shrink as depth grows.
Despawn¶: Hide a sprite and return it to its pool: SpritePool.despawn(). Despawning a sprite twice raises ValueError.
Display¶: The disc the rotor sweeps out. X is an angle that wraps around it; Y is a distance inward from the rim. See The circular display.
Drawable¶: Anything a layer draws: a sprite, a sprite pool, a tilemap or a label. A layer creates its own drawables; there is no free-standing Sprite(...).
Edge¶: An input test that is true for exactly one tick: just_pressed() and just_released(). Compare level.
Emulator¶: Runs your game on a computer with the same renderer semantics as the console. It does not enforce the per-column deadline.
Flip¶: flip_x=True mirrors a sprite, tilemap or label left to right and flip_y=True mirrors it top to bottom. Both together turn it through 180 degrees, which is how a label reads upright at the top of the display. See Tilemaps and text.
Frame¶: One image inside a strip, counted from 0. Setting a sprite’s frame never changes whether it is visible.
Garbage collection¶: How MicroPython frees memory that nothing refers to any more. On the console it runs only when a scene starts or ends, so garbage made every tick piles up until then and a long game can run out of memory; the desktop emulator collects automatically and pauses instead. VS2 avoids both by creating everything in build and reusing it with pools. See Why VS2 works this way.
Glyph¶: The image frame that stands for one character. A glyph table maps characters to frames. See Tilemaps and text.
Idle timeout¶: Seconds without input from either controller before on_idle() fires. The default pops the scene.
Image¶: A strip as loaded from the ROM. Its id defaults to its filename, and frames says how many frames it has.
Label¶: A tilemap you write strings into, with text, write() and set_number(). It counts against the tilemap budget.
Launcher¶: The console’s menu. It finds your game by its folder, so there is nothing to register.
Layer¶: An ordered container of drawables with a projection and a visible flag. Layers paint bottom to top in creation order.
LED¶: One of the 54 lights on the spinning bar. On a vs2.HUD layer, Y is an LED index.
Level¶: An input test that is true while a button is down: held(). Compare edge.
MicroPython¶: A compact implementation of Python 3 for microcontrollers. Games are written in it and run on the console’s ESP32-S3, with limited memory and CPU.
Palette group¶: A set of images in __images__.yaml that share one 256-colour palette. Put images that look alike in the same group.
Pool¶: A fixed group of sprites reserved in build() with sprite_pool(). You spawn and despawn from it instead of creating sprites while the game runs.
Projection¶: How a layer turns Y into LEDs: vs2.TUNNEL, vs2.HUD or vs2.FULLSCREEN. It belongs to the layer, not to its drawables.
Recycle¶: on_empty=vs2.RECYCLE on a pool. An exhausted pool then reuses its oldest live sprite instead of returning None.
Rim¶: The outer edge of the display, at y = 0.
ROM¶: The compiled form of a game’s images: strips, palettes and glyph tables. Frame counts and image sizes are read from it.
Rotation¶: One full sweep of the bar around the disc, a few times per second. It is not tied to update(): at the fan’s usual 400 to 700 RPM there are three to five ticks per rotation.
Rotor¶: The spinning arm that carries the LED bar.
Scene¶: One screen of a game: a subclass of vs2.Scene with a build() and an update(). A game is usually several scenes.
Sealed¶: The state of a scene after build() returns. Existing drawables can be moved, re-framed, shown and hidden, but creating new ones raises vs2.SceneSealedError.
Spawn¶: Take a free sprite from a pool, position it and show it: SpritePool.spawn(). It returns None when the pool is empty. Opposite of despawn.
Sprite¶: One image on a layer, with x, y, frame and visible.
Strip¶: A horizontal filmstrip of equally sized frames in one PNG. A four-frame animation is a PNG four times as wide as one frame.
Tick¶: One call to update(). Ticks come every 30 ms, about 33 a second, whatever the fan speed.
Tile¶: One picture in a tilemap’s tileset, referred to by its frame number. Tile size comes from the image.
Tilemap¶: A grid of cells drawn from a tileset strip, costing one renderer record however many cells it has. Good for terrain and backdrops.
Timer¶: A callback queued with call_later(). Pending timers are discarded when the scene is popped or suspended.
Transition¶: push(), pop() or switch(). It is queued and committed at the end of the tick.
View¶: The fixed window a tilemap shows onto its grid. Scrolling moves the view (view_x, view_y), not the data.
Visible¶: Whether a drawable or layer is drawn. It is independent of a sprite’s frame.