GX engine reference

GX is the standard D/BASIC game engine library. It supplies portable game concepts—scenes, entities, tile worlds, cameras, collision, animation, input, resources, text, and sound—while the runner supplies the physical route that presents them.

Alpha reference

D/BASIC and GX are in alpha, so some engine families in this reference are not yet admitted by every compiler, runner, or target.

Import and delivery

gx is a protected, ASCII-case-insensitive standard module name. A project-local gx.bas cannot shadow it.

IMPORT gx

The default is BAKED: the compiler assembles the reviewed source into the program image.

IMPORT gx BAKED

The explicit shared form compiles against and pins an exact installed library artifact:

IMPORT gx SHARED

A shared dependency records library identity, version, export signature, and byte digest. Missing or different bytes refuse before the game starts. Baked and shared delivery have the same BASIC meaning; they differ only in packaging and reuse.

The browser playground currently demonstrates the baked form. Packaged D/OS and developer-kit runners are the natural home for the installed .dbl form.

Capability map

Family	What game authors get	Natural runner/Intent route
scenes	world bounds, lifecycle, ticks, active scene, scaling policy	window lifecycle and frame scheduling
backgrounds	layered imagery, wrap and parallax factors	retained resource composition
entities and sprites	identity, position, size, kind, velocity, z-order, visibility	GFX retained surfaces and sprite routes
tilemaps and tilesets	row/column/layer data, tile lookup, animated tiles, viewport projection	tilemap/resource GFX operations
collision and physics	rectangle queries, layers, gravity/velocity integration, collision results	local model math or admitted batched compute
cameras	follow, clamp, scroll, world-to-screen projection	scene viewport and surface movement
animation	tick-based frame selection and playback state	resource-region selection and presentation
input and devices	actions mapped from keyboard, pointer, controller, joystick, or paddle	normalized events and frame-coherent snapshots
fonts and text	logical font roles, metrics, game text and overlays	GFX.DRAW_TEXT with per-runner font upgrading/lowering
sound and music	semantic tones, effects, music and bounded streams	AUDIO capability and PCM lifecycles
resources	images, maps, fonts and sounds by package identity	validated, load-once resource providers
tools and diagnostics	map/tileset inspection, debug overlays, capability reports	developer tools over the same public formats

GX does not give a game ambient file access, a native pointer, a video register, or an unmetered callback. Every crossing stays inside the D/BASIC Service and Intent contract.

Current core carrier layout

All current carriers are rank-one INTEGER arrays owned by the caller.

Scene carrier

Allocate at least eight words. Any lower bound is accepted; offsets are relative to LBOUND(Scene, 1).

Offset constant	Offset	Meaning
GX_SCENE_MAGIC_AT	0	GX carrier marker
GX_SCENE_VERSION_AT	1	layout version
GX_SCENE_WIDTH_AT	2	world width
GX_SCENE_HEIGHT_AT	3	world height
GX_SCENE_TICK_AT	4	current bounded tick
GX_SCENE_ACTIVE_AT	5	active flag
reserved	6–7	future compatible state; do not repurpose

Constants: GX_SCENE_WORDS = 8, GX_SCENE_MAGIC = 18248, and GX_SCENE_VERSION = 1.

Entity carrier

Each entity occupies ten consecutive words. Capacity is the complete-word count divided by ten; trailing partial words are ignored.

Offset constant	Offset	Meaning
GX_ENTITY_ALIVE_AT	0	live flag
GX_ENTITY_X_AT, GX_ENTITY_Y_AT	1, 2	world position
GX_ENTITY_WIDTH_AT, GX_ENTITY_HEIGHT_AT	3, 4	collision geometry
GX_ENTITY_VX_AT, GX_ENTITY_VY_AT	5, 6	velocity per step
GX_ENTITY_FRAME_AT	7	retained frame value
GX_ENTITY_FRAME_TICK_AT	8	retained animation tick
GX_ENTITY_KIND_AT	9	application-defined kind

Constant: GX_ENTITY_WORDS = 10.

Tile carrier

Tiles are one word per cell in row-major order. The current carrier requires LBOUND(Tiles, 1) = 0, allowing -1 to remain the unambiguous refused-index result.

index = Y * Columns + X

The declared Columns × Rows product must fit in the carrier and in the current integer-addressable tile index.

Camera carrier

Allocate at least two words. GX_CAMERA_X_AT = 0 and GX_CAMERA_Y_AT = 1; offsets are relative to the array's lower bound.

Current core procedures and functions

Carrier and scene

Words = GXCarrierWords(Carrier())
Ready = GXSceneReady(Scene())
CALL GXSceneOpen(Scene(), Width, Height)
CALL GXSceneAdvance(Scene())

• GXCarrierWords returns the number of elements between the rank-one bounds.
• GXSceneReady returns -1 only when marker and version are valid.
• GXSceneOpen requires eight words and positive dimensions; otherwise it leaves state unchanged.
• GXSceneAdvance requires a ready scene and wraps its tick from 32767 to 0.

Entities

Capacity = GXEntityCapacity(Entities())
Valid = GXEntityValid(Entities(), Slot)
At = GXEntityBase(Entities(), Slot)

CALL GXEntitySpawn(Entities(), Slot, X, Y, Width, Height, Kind)
CALL GXEntityVelocity(Entities(), Slot, VX, VY)
CALL GXEntityStep(Entities(), Slot)

X = GXEntityX(Entities(), Slot)
Y = GXEntityY(Entities(), Slot)

• slots are zero-based even when the carrier itself has another lower bound;
• spawn requires a complete slot and positive size;
• velocity and step affect only a valid, alive entity;
• getters return zero for an invalid slot; and
• GXEntityBase is a low-level layout helper and does not itself validate the slot.

Collision

Hit = GXRectOverlap(AX, AY, AW, AH, BX, BY, BW, BH)
Hit = GXEntitiesOverlap(Entities(), LeftSlot, RightSlot)

Both functions return -1 for overlap and 0 otherwise. Widths and heights must be positive. Edge contact without shared area is not a hit. Rectangle far edges are formed in LONG, preventing integer-edge wraparound from becoming a false collision.

Tiles

At = GXTileIndex(Tiles(), Columns, Rows, X, Y)
CALL GXTileSet(Tiles(), Columns, Rows, X, Y, Tile)
Tile = GXTileAt(Tiles(), Columns, Rows, X, Y)

GXTileIndex returns -1 on an invalid map or coordinate. GXTileSet then leaves the carrier unchanged; GXTileAt returns 0. If zero is meaningful in your game, validate the index first when you need to distinguish “tile zero” from “invalid request.”

Camera

CALL GXCameraFollow(Camera(), FocusX, FocusY, WorldWidth, WorldHeight, ViewWidth, ViewHeight)
X = GXCameraX(Camera())
Y = GXCameraY(Camera())

Follow centers and clamps each axis. A viewport larger than the world clamps that axis to zero. Invalid dimensions leave the camera unchanged; getters return zero for an undersized carrier.

Animation

Frame = GXAnimationFrame(FirstFrame, FrameCount, Tick, TicksPerFrame)

The result is:

FirstFrame + ((Tick \ TicksPerFrame) MOD FrameCount)

An invalid count, duration, or negative tick returns FirstFrame. The function does not wait or draw.

Ownership rules

Thing	Owner
game rules, scores, quests and save decisions	application
GX arrays and object model	application
checked carrier transformations	GX
decoded image/audio/font representation	runner resource provider
input normalization	runner
frame and audio presentation	admitted Intent provider
installed .dbl bytes and binding receipt	package/runner

This division prevents a target adapter from becoming a private edition of the game.

Return and refusal conventions

• BASIC truth is -1; false is 0.
• checked mutators leave state unchanged when their preconditions fail.
• queries use a documented neutral value such as 0 or -1 for invalid input.
• unavailable host capabilities refuse by stable family and operation.
• ticketed work may yield and resume in a later bounded runner turn.
• a failed resource, data, or audio operation must not publish partial success.

When a neutral query value could also be valid game data, validate first or keep an explicit status in the owning game object.

The compatibility qualification

The complete engine qualification is intentionally larger than the currently admitted core:

• 121,067 bytes of upstream declaration and implementation source;
• 126 unique public callable names represented by 152 public bodies;
• 17 official sample programs spanning collision, devices, fonts, maps, tilesets, physics, overworlds, and full game demos; and
• the broader 96-game D/BASIC language corpus beneath it.

The suite keeps those rungs separate. Passing the core proves the documented core API. It does not silently promote the entire engine surface. See What GX Is for the three-ring test story.

Related reference

• Your First GX Game
• Worlds, Animation & Effects
• GX on 6502 & Intent Acceleration
• Resources, Images & Sound
• Windows & Events
• Imports & Libraries

---

Next: GX on 6502 & Intent Acceleration →