🦊 Glossary

Terminology and naming conventions used across Vulfram.

1. Core Concepts

Host

External program that drives Vulfram via the C-ABI.

Examples: Node.js binding, Lua runtime, Python extension, or WASM host.

Responsibilities:

Own game logic and state
Generate logical IDs
Send command batches
Drive the frame loop
Consume responses and events

Core

The Rust dynamic library that implements Vulfram.

Responsibilities:

Window and input management
GPU resources and pipelines
Command processing
Rendering

ABI

The C-compatible function surface exposed by the core:

vulfram_init, vulfram_send_queue, vulfram_tick, ...
Plain C types only (u32, pointers, size_t)

Bindings wrap the ABI in a higher-level API.

2. Components vs Resources

Component

A scene-level entity owned by the host and identified by a logical ID.

Examples: Camera, Model, Light.

Characteristics:

Created and updated by MessagePack commands
Holds per-instance data (transform, layer mask, order)
References resources by ID

Resource

Reusable asset or configuration referenced by components.

Examples: Geometry, Material, Texture.

Resources are sharable and addressed by logical IDs.

Label

An optional semantic name attached to a resource or component to help with debugging and tooling. Labels are not used for indexing.

3. IDs and Handles

Logical IDs (Host-visible)

Integers defined by the host:

WindowId
CameraId
ModelId
LightId
GeometryId
MaterialId
TextureId
BufferId

Handles (Core-only)

Internal references to GPU or runtime state (buffers, textures, pipelines). Never exposed through the ABI.

4. Uploads and Buffers

Upload

A raw byte blob sent with vulfram_upload_buffer.

Identified by (BufferId, UploadType)
Consumed once by a Create* command
Cleared manually with CmdUploadBufferDiscardAll

Fallback Resource

Default resource used when a referenced ID does not exist yet. Allows rendering to continue while assets load.

5. Queues

Command Queue

Host → Core. MessagePack batch sent via vulfram_send_queue. Consumed during vulfram_tick.

Response Queue

Core → Host. Acknowledgements, errors, and internal notices. Retrieved via vulfram_receive_queue.

Event Queue

Core → Host. Input/window/gamepad events. Retrieved via vulfram_receive_events.

6. LayerMask

A u32 bitmask used for visibility filtering.

Rule:

text

Visible if (layerMaskCamera & layerMaskComponent) > 0

7. Naming Conventions

Public ABI functions are prefixed with vulfram_.
Command types follow CmdXxxYyy (e.g. CmdWindowCreate).
Result types follow CmdResultXxxYyy.