Fantasy Pi Console

ISA Instruction Set Architecture

The Fantasy Pi VM is a 32-bit RISC processor with 16 general-purpose registers, 32 fixed-length instructions, and 4 condition flags.

Instruction Format

Every instruction is exactly 32 bits wide and follows this layout:

OP = opcode (6 bits)  |  COND = condition code (4 bits)  |  DST = destination register (4 bits)  |  SRCA/SRCB = source registers (4 bits each)  |  IMM10 = 10-bit signed immediate (10 bits)

For load and jump instructions the lower 22 bits form a signed 22-bit immediate (IMM22).

Condition Codes

The upper 4 bits of every instruction are a condition predicate. The instruction only executes if the predicate is true.

ALU & Data-Processing Opcodes

Memory Opcodes

Control Flow Opcodes

Flag Bits

Assembly Example

Copy; Set up stack and call main
.global _start
_start:
    load    sp, #0x000FFFFC       ; STACK_TOP
    call    main_init

; Simple loop: sum 0..99 in r0
sum_loop:
    load    r0, #0              ; accumulator
    load    r1, #1              ; step
    load    r2, #100            ; limit
.loop:
    add     r0, r1
    cmp     r0, r2
    jlt     .loop
    ret

SYS System Trap Reference

Traps are system calls invoked with the trap instruction. The trap vector (0–1023) is passed in the lower 10 bits of the instruction. Registers R0–R15 are used for arguments and return values according to the calling convention below.

Graphics Traps (0x10 – 0x18)

Blend Modes

Audio Traps (0x20 – 0x22)

Input Traps (0x30 – 0x32)

Input State Layout (RAM 0x00010000)

Copystruct InputState {
    uint32_t keyboard_keys[8];      // 256 key bits
    uint32_t gamepad_buttons[2];  // 2 players
    int16_t  gamepad_axis[2][4];  // LX, LY, RX, RY
    uint32_t mouse_x;
    uint32_t mouse_y;
    uint32_t mouse_buttons;
};

Memory Traps (0x40 – 0x41)

Math Traps (0x50 – 0x52)

Debug Traps (0x60 – 0x61)

Core Traps

Trap Usage Example

Copy; Clear screen to black and draw a sprite
    load    r0, #0xFF000000       ; black (ARGB)
    trap    0x12               ; GFX_CLEAR

    load    r0, #0              ; sprite ID
    load    r1, #100            ; x
    load    r2, #200            ; y
    load    r3, #1              ; Alpha blend mode
    trap    0x13               ; GFX_DRAW_SPRITE

    trap    0x11               ; GFX_PRESENT

MEM Memory Map & Registers

Memory Layout

Register File

The VM exposes 16 general-purpose 32-bit registers (R0–R15). Several registers have dedicated roles in the ABI:

Hardware Limits

CPP C++ SDK Reference

The C++ runtime abstracts the virtual hardware through a thin header-only layer. You write game logic against these headers; the IDE generates asset IDs, scene IDs, GameObject type IDs, and named GameObject instance IDs automatically.

Engine Lifecycle

Copy#include <fantasy_engine.h>

int main() {
    fe::Engine_Init();               // Set up subsystems
    fe::Engine_LoadScene(SCENE_FOREST_01);

    while (true) {
        fe::Engine_PollInput();      // Update input state
        fe::Engine_Update();         // Run all GO_Update callbacks
        fe::Engine_Draw();           // Draw tilemaps + GO_Draw callbacks
    }
    return 0;
}

Graphics API

Sprite & Tilemap API

Input API

Button Constants

Audio API

GameObject API

GameObjects are the primary gameplay entities. The IDE generates type IDs and a registration table from the GameObject Editor. You only implement the callback functions.

Named Map Instances

When you paint on an Object layer in the Studio Map editor, the selected tile is stored as map data and a real GameObjectInstance is attached to that map. Select the painted object and set its Instance-Name in the right-side settings panel. During code generation the IDE writes generated/gameobject_instances.h with one GOINST_* constant per named instance.

Copy// Object layer instance name in the Map editor: player
#include <fantasy_engine.h>

void Door_Update(GameObject* self) {
    GameObject* player = fe::GO_GetInstance(GOINST_PLAYER);
    if (player) {
        Vec2 p = fe::GO_GetPos(player);
        if (p.x > 120) {
            fe::GO_SetPos(self, 200, self->pos.y);
        }
    }
}

GameObject Registration Macro

Copy// In a .cpp file — the IDE generates the registry automatically
#include "generated/gameobject_types.h"

struct EnemyData { int hp; int patrolDir; };

void EnemySlime_Init(GameObject* self) {
    auto* d = static_cast<EnemyData*>(self->user_data);
    d->hp = 3;
    d->patrolDir = 1;
    self->sprite_id = ASSET_SPR_ENEMY_SLIME;
    self->collider = { 0, 0, 16, 16 };
}

void EnemySlime_Update(GameObject* self) {
    auto* d = static_cast<EnemyData*>(self->user_data);
    self->pos.x += d->patrolDir;
    if (self->pos.x > 200 || self->pos.x < 50)
        d->patrolDir = -d->patrolDir;
}

void EnemySlime_OnCollision(GameObject* self, GameObject* other) {
    if (other->type_id == GOID_PLAYER) {
        fe::Engine_PlaySFX(ASSET_SFX_HIT, 0);
    }
}

Math & Utility

Complete Project Structure