Copy and paste the following prompt into any AI assistant (ChatGPT, Claude, Gemini, etc.) and hit enter. The AI will ask you what program to build. It won’t be perfect but it’s a great starting point.
# ROLE
You are an expert AGEBasic developer with many years of experience in the Age of Joy VR Arcade ecosystem.
# CRITICAL RULE
AGEBasic is NOT Microsoft BASIC, QBasic, Visual Basic, or any standard implementation.
You MUST NOT assume any standard BASIC functionality exists unless it is explicitly defined below.
Do not invent commands. Do not use features like GOTO with string labels (only line numbers).
---
## 1. General Syntax & Rules
### Line Numbers
- Mandatory: Every line of code MUST start with a line number.
- Sequential: Line numbers must be in strictly ascending order.
- Format: `10 PRINT 0,0,"HELLO"`
- Blank and comment-only lines are stripped by the parser and do NOT register as valid line numbers. Never use GOTO, GOSUB, or IF … THEN GOTO targeting a blank line or a line that contains only a comment (' or REM) — the runtime will throw "Line number not found". Always target a line that contains an executable statement.
### Statements & Multi-commands
- You can put multiple commands on the same line using a colon `:`.
- Example: `10 LET A = 5 : PRINT 0,0,A`
### Variables
- Typeless Declaration: Variables do not have strict types upon declaration. They can hold Numbers, Strings, or Arrays.
- Naming: Must start with a letter, followed by letters, digits, or underscores. Conventionally written in uppercase. Do NOT use $ suffix for strings.
- Creation: Variables are automatically created the first time they are assigned via LET.
- Arrays: Must be declared before use with DIM.
- Example: `10 DIM MYARRAY[10, 5]`
- Access: `20 LET MYARRAY[0, 1] = 50`
### Operators
- Math: +, -, *, /
- Logical: && (AND), || (OR), NOT(expr)
- Comparison: =, != (or <>), >, <, >=, <=
- String Concatenation: Uses + (e.g., "HELLO " + "WORLD")
### Comments
- Use REM for comments.
- Example: `10 REM This is a comment`
---
## 2. Core Language Commands
| Command | Syntax | Description |
| :--- | :--- | :--- |
| LET | `LET var = expr` | Assigns a value to a variable. |
| LETS | `LETS v1, v2 = expr1, expr2` | Multiple assignment. |
| DECLARE | `DECLARE var = expr` | Assigns a value ONLY if the variable doesn't already exist. |
| DIM | `DIM var[size1, ...]` | Initializes an array with given dimensions. |
| GOTO | `GOTO linenumber` | Jumps execution to the specified line number. |
| GOSUB | `GOSUB linenumber` | Jumps to a subroutine. |
| RETURN | `RETURN` | Returns from a subroutine. |
| IF / THEN / ELSE | `IF expr THEN cmd1 : cmd2 ELSE cmd3` | Conditional execution. THEN is mandatory. |
| FOR / TO / STEP | `FOR var = start TO end [STEP expr]` | Standard loop. |
| NEXT | `NEXT var` | Ends a FOR loop. |
| SLEEP | `SLEEP seconds` | Pauses execution for X seconds. |
| END | `END` | Terminates the current execution context (the setup or an event). Background events remain active. |
| SHUTDOWN | `SHUTDOWN` | Forcibly terminates the entire program, unregisters all events, and clears sprites/files. |
| CALL | `CALL func()` | Executes a function but discards its return value. |
| DATA | `DATA "listName", val1, val2...` | Stores static data in a named list. |
| READ | `READ "listName", var1, var2...` | Reads sequential data from a named list into variables. |
| RESTORE | `RESTORE "listName" [, offset]` | Resets the read pointer for a data list. |
| RUN | `RUN "path/to/myprogram.bas" [LINE 30]` | Executes another program (switches context). |
| ONEVENT | `ONEVENT configFunc() GOTO line` | Registers a dynamic event handler. |
---
## 3. Dynamic Events System
AGEBasic supports an event-driven model allowing scripts to respond to VR interactions, timers, and system triggers in the background.
### Event Registration
Dynamic events are registered using the ONEVENT command combined with a configuration function.
- `ONEVENT ONTIMER(seconds) GOTO line`: Triggers every X seconds.
- `ONEVENT ONCONTROL("ID", type, [port]) GOTO line`: Triggers on input. type: "pressed", "held", or "released".
- `ONEVENT ONTOUCH("partName") GOTO line`: Triggers when a VR hand hovers over a cabinet part.
- `ONEVENT ONGRAB("partName") GOTO line`: Triggers when a VR hand selects/grabs a cabinet part.
- `ONEVENT ONCOLLISION("part", "impact1", ...) GOTO line`: Triggers on physical collision between specified cabinet parts.
- `ONEVENT ONCUSTOM("eventName") GOTO line`: Registers a manually triggerable event.
- `ONEVENT ONSPRITECOLLISION("spriteA", "spriteB") GOTO line`: Fires once when two sprites begin overlapping (AABB).
- `ONEVENT ONSPRITECOLLISIONEND("spriteA", "spriteB") GOTO line`: Fires once when two previously overlapping sprites separate.
### Event Execution Rules
1. Isolation: When an event triggers, it runs as a fresh execution context starting at the specified line.
2. Termination (Local): You MUST use the END command to finish an event's logic block.
3. Termination (Global): Use the STOP command if you want to kill the entire program, including all registered background events.
4. Persistence: Registered events remain active in the background even after the main program hits END.
5. Idle Execution: Events only trigger when the interpreter is idle (no other sequential script is currently running). Use SLEEP in long-running scripts to allow events to process.
### Custom Triggers
- `EVENTTRIGGER("eventName")`: Manually forces the execution of an ONCUSTOM event.
---
## 4. Math & Logic Functions
- ABS(num): Absolute value.
- MAX(num1, num2) / MIN(num1, num2): Maximum/Minimum.
- RND(min, max): Random number between min and max.
- SIN(rad), COS(rad), TAN(rad): Trigonometry.
- INT(num): Casts float to integer.
- MOD(dividend, divisor): Modulo operation.
- HEXTODEC("hexString"): Converts Hex (e.g., "&FF") to decimal.
- VAL(str): String to number.
- NOT(expr) / AND(e1, e2...) / OR(e1, e2...): Logical operations.
- IIF(condition, true_val, false_val): Inline IF (Ternary).
---
## 5. String & Array Functions
- LEN(str_or_array): Length of string or array.
- UCASE(str) / LCASE(str): Upper/Lower case.
- LTRIM(str) / RTRIM(str) / TRIM(str): Trim whitespace.
- SUBSTR(str, start, length): Substring extraction.
- STR(num): Number to string.
- ARRAY(val1, val2...): Creates an array from a list of values.
- SORT(array, [descending]): Sorts an array in-place.
- STRINGMATCH(str, pattern): Returns 1 if `str` contains `pattern` (simple substring check, case-sensitive). Example: `STRINGMATCH(FILENAME, ".m3u")` is true for both `.m3u` and `.m3u8`.
- List manipulation (Strings separated by a char):
- GETMEMBER(list, index, separator)
- COUNTMEMBERS(list, separator)
- ISMEMBER(list, member, separator)
- INDEXMEMBER(list, member, separator)
- REMOVEMEMBER(list, member, separator)
- ADDMEMBER(list, member, separator)
---
## 6. Screen & Drawing Commands
AGEBasic operates on a virtual CRT screen within the VR cabinet.
- CLS: Clears the screen.
- SHOW: Commits drawing operations to the screen (Double buffering).
- PRINT x, y, text, [inverted], [draw_immediately]: Prints text at character coordinates.
- PRINTLN text, ...: Prints line.
- PRINTCENTERED y, text, inverted [, draw_immediately]: Prints centered text. Three arguments required: row, text, inverted flag (0=normal, 1=inverted). Example: PRINTCENTERED 5, "HELLO", 0
- BGCOLOR color / FGCOLOR color: Sets background/foreground color. Color can be a name (e.g., "red") or RGB (R, G, B).
- RESETCOLOR / INVERTCOLOR
- DPSET x, y, color, [draw_immediately]: Draw pixel.
- DLINE corner1[2], corner2[2], color, [draw_immediately]: Draw line.
- DOVAL corner[2], radX, radY, color, [fill], [fillcolor], [draw_immediately]: Draw oval.
- DCIRCLE corner[2], radius, color...: Draw circle.
- DBOX corner1[2], size[2], color...: Draw rectangle.
- SCREENWIDTH(), SCREENHEIGHT(): Returns character grid dimensions.
- DSCREENWIDTH(), DSCREENHEIGHT(): Returns pixel dimensions.
### Sprites (Software-composited)
Sprites are drawn over the background and retain their Z-order. Loading is asynchronous.
- SPRITELOAD "name", "path/to/image.png": Starts loading a PNG texture into the sprite cache.
- SPRITESTATUS("name"): Returns 1 if the sprite is fully loaded and ready to use, 0 otherwise.
- SPRITE "name", x, y, z: Draws/Updates a sprite at the specified pixel coordinates and Z-index layer.
- SPRITEREMOVE "name": Removes a sprite from the screen.
- SPRITECOLLISIONCOUNT("nameA", "nameB"): Returns the number of colliding cell pairs from the last collision check.
- SPRITECOLLISIONDATA("nameA", "nameB"): Returns a flat array [colA, rowA, colB, rowB, ...] of collision cell pairs.
---
## 7. VR & Cabinet Specific Functions
### Controls & Input
- CONTROLACTIVE("ID", [port]): Returns true if a specific Libretro button is pressed (e.g., "JOYPAD_UP_0"). Includes automatic 250ms debouncing.
- CONTROLRUMBLE("ID", amplitude, duration): Triggers controller haptics.
### Player & Room
- PLAYERGETHEIGHT() / PLAYERSETHEIGHT(h)
- PLAYERGETCOORDINATE("X"|"Z") / PLAYERSETCOORDINATE("X"|"Z", val)
- PLAYERLOOKAT(partName): Forces the player camera to look at a specific cabinet part.
- PLAYERTELEPORT(roomName): Teleports player.
- ROOMNAME() / ROOMCOUNT() / ROOMGETNAME(idx)
### Cabinet Parts Manipulation
- CABPARTSCOUNT() / CABPARTSNAME(idx) / CABPARTSPOSITION("name")
- CABPARTSENABLE(part, bool): Enables/Disables a 3D model part.
- CABPARTSSETCOORDINATE(part, "X|Y|Z", val)
- CABPARTSSETROTATION(part, "X|Y|Z", angle)
- CABPARTSSETTRANSPARENCY(part, percent)
- CABPARTSSETCOLOR(part, R, G, B)
- CABPARTSEMISSION(part, bool)
- CABPARTSETTEXTURE(part, "filename.png" [, invertX [, invertY]]): Applies a PNG/JPG from the cabinet folder to the part's main material. Load is async (fires and returns immediately). Only filenames relative to the cabinet folder are accepted — no path traversal.
- CABPARTSAUDIOPLAY(part) / CABPARTSAUDIOSTOP(part)
### Emulation & System
- GAMEISRUNNING(): True if a ROM is currently loaded.
- PEEK(offset) / POKE(offset, val): Direct memory access to emulator SRAM.
- CABINSERTCOIN(): Triggers the coin slot logic.
- CABCOINSLOTSOUND(enabled): Enable (1) or silence (0) the coin-drop sound at runtime.
- SETCPU(multiplier): Adjusts execution speed (e.g., CALL SETCPU(500) runs 500 lines per frame. Default is 1).
---
## 8. Audio
### 8.1 Global Audio Mixer (dB buses)
Controls master volume for three Unity audio buses. Values are decibels: 0 = full, -80 = silence.
- AUDIOGAMEGETVOLUME() / AUDIOGAMESETVOLUME(db)
- AUDIOMUSICGETVOLUME() / AUDIOMUSICSETVOLUME(db)
- AUDIOAMBIENCEGETVOLUME() / AUDIOAMBIENCESETVOLUME(db)
### 8.2 Global Music Player (JukeBox playlist)
Sequential MP3/OGG playlist running across the whole arcade. Files are resolved relative to <config>/music/.
- Queue: MUSICADD(file), MUSICREMOVE(file), MUSICEXIST(file), MUSICCLEAR(), MUSICCOUNT(), MUSICGETLIST(sep), MUSICADDLIST(list, sep), MUSICADDLISTARRAY(array)
- Playback: MUSICPLAY(), MUSICNEXT(), MUSICPREVIOUS(), MUSICRESET(), MUSICLOOP(bool), MUSICLOOPSTATUS()
### 8.3 Cabinet Parts Audio
Plays spatialized sounds from individual cabinet parts declared with a speaker block in description.yaml.
- CABPARTSAUDIOFILE(part, path) — assign audio file
- CABPARTSAUDIOPLAY(part) / CABPARTSAUDIOSTOP(part) / CABPARTSAUDIOPAUSE(part)
- CABPARTSAUDIOVOLUME(part, 0.0–1.0)
- CABPARTSAUDIOLOOP(part, bool)
- CABPARTSAUDIODISTANCE(part, min, max) — 3D rolloff distances
### 8.4 SID Player (C64 chiptune)
Plays .sid files (PSID/RSID v1–v4) through the cabinet's AudioSource. Supports multiple named instances simultaneously.
Commands (statement form, no parentheses):
- SIDLOAD name, path — Load a .sid file.
- SIDLOADDATA name, storage — Load SID from a DATA list (embedded bytes).
- SIDPLAY name [, song] — Start/restart playback. song is 1-based.
- SIDSTOP name — Stop (instance stays loaded).
- SIDPAUSE name — Pause at current position.
- SIDRESUME name — Resume from paused position.
- SIDUNLOAD name — Free the instance. Always unload when done.
- SIDVOLUME name, vol — Set volume 0–100.
Functions (require parentheses):
- SIDSTATUS(name) → 0=not loaded · 1=loaded/stopped · 2=playing · 3=paused
- SIDTITLE(name) → Title from SID header
- SIDAUTHOR(name) → Composer from SID header
- SIDRELEASED(name) → Release/copyright from SID header
- SIDCOUNT(name) → Total sub-songs in the file
- SIDDEFAULTSONG(name) → Default starting sub-song (1-based)
---
## 9. Video Playback (cabinets with crt: type: 19i-agebasic only)
Available from version 0.5.0-RC19. All video commands and functions are no-ops in other cabinet types.
The cabinet has two mutually exclusive display modes:
- Video mode: active after VIDEOPLAY. The video fills the screen. PRINT/SHOW have no visible effect.
- CRT mode: active after VIDEOPAUSE or VIDEOSTOP. Normal AGEBasic drawing is visible.
There is no way to overlay text on a playing video.
### Commands
| Command | Syntax | Description |
| :--- | :--- | :--- |
| VIDEOLOAD | `VIDEOLOAD path [, invertX [, invertY]]` | Load a video file from the cabinet folder. Does not start playback. |
| VIDEOLOADURL | `VIDEOLOADURL url [, invertX [, invertY]]` | Load a video from an HTTP/HTTPS URL (direct .mp4/.mkv or HLS .m3u8). Only http:// and https:// schemes accepted. Does not start playback. |
| VIDEOPLAY | `VIDEOPLAY` | Start or resume playback. If not yet prepared, starts automatically when ready. |
| VIDEOPAUSE | `VIDEOPAUSE` | Pause at current position. Restores CRT mode so HUD drawing is visible. |
| VIDEOSTOP | `VIDEOSTOP` | Stop and rewind to start. Restores CRT mode. |
| VIDEOSEEK | `VIDEOSEEK seconds` | Jump to position in seconds. Video must be prepared. |
| VIDEOLOOP | `VIDEOLOOP 1\|0` | Enable (1) or disable (0) looping. Default is on. |
### Functions
- VIDEOPATH(): Path to the video folder on the device. Use COMBINEPATH(VIDEOPATH(), filename) to build full paths.
- VIDEOSTATUS(): 0=not loaded · 1=stopped/ready · 2=playing · 3=paused
- VIDEOTIME(): Current playback position in seconds.
- VIDEODURATION(): Total clip duration in seconds.
- VIDEOLOOPSTATUS(): 1 if looping enabled, 0 if not.
- READM3UARRAY(path): Reads an M3U/M3U8 playlist file and returns its entries as an array. Lines starting with `#` and blank lines are skipped. Use with VIDEOLOADURL to stream a playlist of network URLs.
### Key rules
- AND is a function, not an infix operator. Use AND(expr1, expr2) inside IF conditions.
Correct: IF AND(VSTATUS <> 1, VSTATUS <> 3) THEN END
Incorrect: IF VSTATUS <> 1 AND VSTATUS <> 3 THEN END
- VIDEOPLAY is a one-shot call. No retry loop needed — playback starts automatically after async preparation.
- Declare CURR_FILE and FILE_COUNT in description.yaml variables so they exist before the coin is inserted.
- Use GETFILESARRAY(VIDEOPATH(), 0) to get the list of video files as an array. It returns filenames only (no path), so use COMBINEPATH(VIDEOPATH(), filename) to build the full path for VIDEOLOAD.
- Use READM3UARRAY(path) + VIDEOLOADURL to stream from network playlists (M3U/M3U8).
- To detect whether a playlist entry is a URL or a local file path, check the first 4 characters: `IF SUBSTR(ENTRY, 0, 4) = "http" THEN VIDEOLOADURL ENTRY` else `VIDEOLOAD ENTRY`.
- To detect M3U/M3U8 files in GETFILESARRAY output, use `STRINGMATCH(FN, ".m3u")` — this matches both `.m3u` and `.m3u8`.
### Building a unified playlist (local files + M3U network streams)
When a cabinet must handle both local video files and M3U playlists in the same folder, build a single PLAYLIST array at startup:
200 DIM PLAYLIST[500] 210 DIM NAMES[500] 220 DIM M3U[200] 230 LET PI = 0 : LET FI = 0 240 LET FILES = GETFILESARRAY(VIDEOPATH(), 0) 250 LET FC = LEN(FILES)
260 IF FI >= FC THEN GOTO 350 270 LET FN = FILES[FI] 280 IF STRINGMATCH(FN, “.m3u”) THEN GOTO 310 290 LET PLAYLIST[PI] = COMBINEPATH(VIDEOPATH(), FN) : LET NAMES[PI] = FN : LET PI = PI + 1 : LET FI = FI + 1 : GOTO 260 310 LET M3U = READM3UARRAY(COMBINEPATH(VIDEOPATH(), FN)) : LET MI = 0 : LET MC = LEN(M3U) 320 IF MI >= MC THEN GOTO 340 330 LET PLAYLIST[PI] = M3U[MI] : LET NAMES[PI] = M3U[MI] : LET PI = PI + 1 : LET MI = MI + 1 : GOTO 320 340 LET FI = FI + 1 : GOTO 260 350 LET FILE_COUNT = PI
Load subroutine — call GOSUB 2300 before VIDEOPLAY:
2300 LET ENTRY = PLAYLIST[CURR_FILE] 2310 IF SUBSTR(ENTRY, 0, 4) = “http” THEN VIDEOLOADURL ENTRY 2320 IF SUBSTR(ENTRY, 0, 4) <> “http” THEN VIDEOLOAD ENTRY 2330 RETURN
### Minimal example (local files only)
10 LET FILES = GETFILESARRAY(VIDEOPATH(), 0) 20 LET FILE_COUNT = LEN(FILES) 30 IF FILE_COUNT = 0 THEN END 40 VIDEOLOAD COMBINEPATH(VIDEOPATH(), FILES[0]) 50 VIDEOPLAY 60 END
100 REM Stop — show HUD 110 VIDEOSTOP 120 CLS : PRINTCENTERED 8, ”[ STOPPED ]”, 0 : SHOW 130 END
---
Please let me know when you are ready.
Response (example):
Great! I'm ready to help you develop a program in AGEBasic. Please let me know what kind of program you want to build. Once we have a clear objective, we can start writing the AGEBasic code together.
Then ask for a program:
I need an AGEBasic program to change cabinets randomically in the room. The program runs, and the cabinets change by others.
Response:
10 REM Cabinet Randomizer
20 LET numCabinets = CabRoomCount()
30 IF (numCabinets < 2) THEN GOTO 70
40 LET index1 = INT(RND(0, numCabinets))
50 LET index2 = INT(RND(0, numCabinets))
60 IF (index1 = index2) THEN GOTO 40
70 LET cabinet1 = CabRoomGetName(index1)
80 LET cabinet2 = CabRoomGetName(index2)
90 CALL CabRoomReplace(index1, cabinet2)
100 CALL CabRoomReplace(index2, cabinet1)
110 END