Asset Management

The asset manager handles loading, processing, and lifetime management of all engine assets. It operates at the process level - assets are shared across all worlds, so the same resource is never loaded twice.

Asset Types

Type	Source library	Notes
Models (raw)	Assimp	60+ formats supported. Used during development.
Models (limonmodel)	Native	Engine-native format. Used for release builds. See limonmodel below.
Animations	Assimp	Mixamo retargeting supported.
Textures	SDL2_image	All formats supported by SDL2_image.
Audio	OpenAL	OGG and WAV.
Materials (MaterialAsset)	Model asset or world file	Deduplicated automatically regardless of source. See Materials as Assets below.
Shaders	GLSL	Discovered at launch via runtime reflection.

Loading Pipeline

Asset loading is split into two layers to maximise parallelism while keeping GPU uploads on the main thread:

• CPU layer - a thread pool decompresses, parses, and converts assets in parallel. Each completed asset is pushed to a thread-safe queue.

• GPU layer - the main thread consumes from the queue on a fixed per-frame budget. Texture uploads, vertex buffer creation, and shader compilation are spread across frames to prevent load spikes from dropping below the target framerate.

A world signals ready only after all assets have completed both layers - no partial asset state is visible to the scene. In the editor, a model can only be placed after its loading is fully complete.

Reference Counting

• Objects hold read-only references to managed assets - no object owns an asset outright.

• Reference counting releases assets automatically when no world holds a reference.

• Assets shared between worlds are not reloaded during world transitions and are not double-counted by the reference system.

Materials as Assets

All materials are managed as MaterialAsset objects regardless of origin. A material embedded in a model file and a material defined in the world file are both MaterialAsset instances - the asset manager makes no distinction between them.

If two models reference the same source material, it is loaded once and shared. Custom materials created or modified in the editor are saved in the world file and loaded identically to model-sourced materials.

For how to create and edit materials in the editor, see Using Builtin Editor.

World Transitions

Four API methods control how the asset manager handles memory when switching worlds. The choice trades memory footprint against load time:

Method	Memory	Load time	Description
loadAndSwitchWorld	Higher	Shorter	New world loads while old stays in memory. Assets shared between both worlds are not reloaded. (C++ | Python)
returnToWorld	Higher	Shorter	Returns to a previously loaded world still in memory. (C++ | Python)
loadAndRemove	Lower	Longer	Releases old world and its exclusive assets before loading the new world. (C++ | Python)
returnPreviousWorld	Lower	Longer	Returns to the previous world after releasing the current one. (C++ | Python)

quitGame / quit_game exits the application.

limonmodel - Engine-Native Format

Raw model formats (FBX, OBJ, GLTF, etc.) are suitable for development but carry redistribution restrictions and parse overhead. The limonmodel format is optimised for release:

• Near memory-direct layout - loading is read-and-map rather than parse-and-transform.

• Contains: vertex and index buffers, skeletal animation data, material information, and textures if they were embedded in the source file.

• Texture handling mirrors the source - embedded textures stay embedded; external texture references stay external.

• Faster load times and smaller file size than raw formats.

• Works around raw asset redistribution restrictions.

To convert all models in a world, use the Convert models to binary button in the world editor. The world file is updated to reference the converted assets automatically.

Asset Browser

The editor includes an asset browser organised as a typed directory tree. Different editor panels use type-filtered views of the same browser.

• Model assets - a dedicated preview renders the model using the current world’s directional light.

• Texture assets - a hover preview appears under the cursor. Shared by material texture slots, skybox settings, and GUI image and button elements.

The asset browser with directory tree and 3D model preview.

Model Scaling

The engine assumes 1 unit = 1 meter. If the source model has a unit defined (e.g. centimetres, inches), that unit is used to calculate the import scale automatically. If the source model has no unit defined, or an incorrect one, the model imports at the scale the file specifies. Scale can be corrected at any time in the editor. No heuristic-based correction is applied.