This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Glossary

This page defines the key terminology used throughout the Terrarum game engine.

Core Concepts

Actor

An entity in the game world that can be updated and rendered. Actors are the fundamental interactive objects in the game, including players, NPCs, particles, projectiles, and fixtures. All actors extend the Actor base class and have a unique Reference ID.

Reference ID (Actor ID)

A unique integer identifier assigned to each Actor in the game. Valid Reference IDs range from 16,777,216 to 0x7FFF_FFFF. The Reference ID is used to track and retrieve actors during the game's lifecycle.

Render Order

Determines the drawing layer for actors. From back to front:

FAR_BEHIND — Wires and conduits
BEHIND — Tapestries, some particles (obstructed by terrain)
MIDDLE — Standard actors (players, NPCs, creatures)
MIDTOP — Projectiles, thrown items
FRONT — Front walls (blocks that obstruct actors)
OVERLAY — Screen overlays, not affected by lightmap

ActorWithBody

An Actor that has physics properties, including position, velocity, hitbox, and collision. Most interactive game entities inherit from ActorWithBody rather than the base Actor class.

Hitbox

An axis-aligned bounding box (AABB) that defines an actor's collision area. The engine uses an AABB-based physics system optimised for handling millions of tile bodies.

Block

A tile in the game world. Blocks can be terrain, walls, platforms, or other tile-based objects. Each block has properties such as strength, density, material, luminosity, and collision behaviour.

Wall

A block placed in the wall layer, typically behind terrain. Walls do not provide collision by default but can affect lighting and provide visual background.

Terrain

A block placed in the terrain layer. Terrain blocks typically provide collision and are what players interact with directly.

Tile

A single grid position in the game world. The default tile size is 16×16 pixels (though this can be configured via TILE_SIZE). Used interchangeably with "block" in some contexts.

Item

A game object that can exist in inventories, be dropped in the world, or be used by actors. Items extend the GameItem class and have unique Item IDs.

Item ID

A string identifier for items following the format item@<module>:<id> (e.g., item@basegame:1). For blocks used as items, the format is <module>:<id> (e.g., basegame:32).

Fixture

A special type of actor representing interactable world objects such as doors, chests, crafting stations, and other furniture. Fixtures often have associated UI interactions.

World & Generation

GameWorld

The container for all world data, including terrain layers, fluid simulation, lighting, wirings, and environmental properties. A GameWorld represents a single playable world/dimension.

Chunk

A subdivision of the world used for efficient storage and generation. Chunks are CHUNK_W × CHUNK_H tiles in size. The world generates chunks on-demand rather than all at once, enabling fast world creation for vast world sizes.

Block Layer

A 2D array storing block data for the world. The engine uses multiple specialised layers:

layerTerrain — Foreground blocks with collision
layerWall — Background wall blocks
layerOres — Ore deposits overlaid on terrain
layerFluids — Fluid simulation data

Spawn Point

The tilewise coordinate where players initially appear in a world. Stored as spawnX and spawnY in the GameWorld.

World Time

The in-game time system. Measured in seconds since the world's epoch. The engine simulates day/night cycles, seasons, and celestial events based on world time.

Gravitation

The gravitational acceleration vector applied to physics bodies. Currently, only downward gravity is supported. Default is approximately 9.8 m/s² in game units.

Modules & Loading

Module

A package of game content (blocks, items, actors, code) that can be loaded by the engine. Modules are the modding/extension system for Terrarum. See also: Modules

Internal Module

A module shipped with the game, stored in <game exec dir>/assets/mods/. These modules form the "base game" and become read-only when packaged.

User Module

A user-created mod stored in <appdata>/Modules/. These can be freely modified by end users.

Entry Point

A class extending ModuleEntryPoint that initialises and registers a module's content with the game. The entry point is specified in the module's metadata.properties.

ModMgr

The Module Manager (ModMgr) singleton that handles module loading, dependency resolution, and content registration. It provides loaders for blocks, items, materials, languages, and other game content.

Codex

A registry that stores game content by ID. The engine maintains several codices:

BlockCodex — All blocks and terrain types
ItemCodex — All items
WireCodex — All wire/conduit types
MaterialCodex — All material definitions
FactionCodex — All faction definitions
CraftingCodex — All crafting recipes
AudioCodex — All audio assets
WeatherCodex — All weather types
FluidCodex — All fluid types
OreCodex — All ore types

UI System

UICanvas

The base class for all UI screens and windows. A UICanvas can contain UIItems and sub-UIs, and manages its own show/hide animations and event handling.

UIItem

An individual UI element (button, slider, text field, etc.) that can be added to a UICanvas. UIItems have event listeners for clicks, drags, keyboard input, and updates.

UIHandler

Manages the lifecycle and state of a UICanvas, including opening/closing animations, positioning, and visibility state.

IngameInstance

A game screen that represents an active game session. Extends LibGDX's Screen interface and manages the game world, actors, UI, and rendering pipeline. The title screen and ingame view are both IngameInstances.

Graphics & Rendering

Autotiling

A system that automatically selects the correct sprite variant for blocks based on neighbouring blocks. Terrarum uses a 7×7 tile atlas (112×112 pixels) for full autotiling support with connection rules.

Tile Atlas

A texture atlas containing all variants of a block's sprite for autotiling. The engine supports several atlas formats: 16×16 (single tile), 64×16 (wall stickers), 128×16 (platforms), 112×112 (full autotiling), and 224×224 (seasonal autotiling).

Lightmap

A texture representing the light levels (RGB+UV) for each tile in the visible area. The engine simulates realistic light propagation with transmittance and supports both static and dynamic light sources.

Dynamic Light Function (dlfn)

Defines how a luminous block's light output changes over time:

0 — Static (constant brightness)
1 — Torch flicker
2 — Current global light (sun, star, moon)
3 — Daylight at noon
4 — Slow breath (gentle pulsing)
5 — Pulsating (rhythmic)

FlippingSpriteBatch

A custom SpriteBatch implementation used throughout the engine for rendering sprites and textures.

WorldCamera

The orthographic camera that determines what portion of the world is currently visible on screen.

Shader

GLSL programs running on the GPU to render special effects. Terrarum uses OpenGL 3.2 Core Profile with GLSL version 1.50. Shaders are stored in src/shaders/.

Physics & Collision

AABB

Axis-Aligned Bounding Box. The collision detection system used by the engine. All hitboxes are rectangular and aligned to the world axes (not rotated).

Phys Properties

Physical properties of an ActorWithBody, including:

Mass — Affects momentum and collision response
Friction — How much the actor resists movement on surfaces
Immobile — Whether the actor can move or is fixed in place
Density — Mass per unit volume (water = 1000 in game units)

METER

A fundamental constant defining the relationship between pixels and physics simulation. As of the current version, 1 metre equals 25 pixels. This constant is used throughout physics calculations.

PHYS_TIME_FRAME

The time step used by the physics simulator. Currently set to the value of METER for convenient 1:1 correspondence between game units and SI units.

Audio

AudioMixer

The central audio system managing all sound output. Supports spatial audio, effects processing, and mixer buses.

Track

An audio channel in the mixer. The engine provides multiple dynamic tracks for music and sound effects, each with independent volume control, filters, and effects.

MusicContainer

A wrapper for music assets in the AudioBank. Manages music playback with crossfading and looping.

Spatial Audio

3D sound positioning system that adjusts volume and panning based on the listener's position relative to the sound source.

Serialisation & Save/Load

VirtualDisk

The file archival format used for save games. Based on the TerranVirtualDisk library. Each savegame consists of a world disk and a player disk.

Disk Skimmer

A utility for reading savegame metadata without loading the entire save file. Used for displaying save information in load screens.

Transient

A Kotlin annotation (@Transient) marking fields that should not be serialised when saving the game state. Transient fields must be reconstructed when loading.

Reload

A method called on actors after deserialisation to reconstruct transient fields and re-establish references.

Internationalisation

Lang

The language system managing text translations. Supports 20+ languages with dynamic font switching.

IME

Input Method Editor. Allows entry of complex scripts (e.g., Chinese, Japanese, Korean) using keyboard layouts. See also: Keyboard Layout and IME

Low Layer

The base keyboard layout (typically Latin characters like QWERTY) used by the IME.

High Layer

The advanced keyboard layout for complex scripts managed by the IME. Can be phonetic (reading from Low Layer) or independent.

Terrarum Sans Bitmap

The custom bitmap font system supporting multilingual text rendering. Maintained in a separate repository.

Configuration

App Config

Global engine configuration stored in config.json in the appdata directory. Includes graphics settings, controls, audio settings, and debug options.

Module Config

Configuration specific to a module. Default values are in <module>/default.json, with user modifications stored in the global config file with the module name prefix (e.g., basegame:config_key).

TILE_SIZE

A configurable constant defining the pixel dimensions of one tile. Default is 16 pixels. Changing this requires engine recompilation.

Debugging

Debug Mode

Enabled when IS_DEVELOPMENT_BUILD is true. Activates additional logging, assertions, and debug visualisations.

Console

An in-game developer console accessible during gameplay (typically via F12). Allows executing commands, spawning items/actors, and manipulating game state.

hs_err_pid

Log files generated by the JVM when it crashes. Useful for debugging native crashes during development.

Miscellaneous

Faction

A group affiliation system for actors. Factions can have relationships (friendly, neutral, hostile) that affect AI behaviour and combat.

Weather

Environmental effects like rain, snow, or fog. Managed by the WeatherMixer and can affect visibility, lighting, and gameplay.

Wire / Conduit

A special type of block placed in the FAR_BEHIND render layer that connects devices and transmits signals or resources. Multiple wire types can occupy the same tile position.

Wirings

A hash map storing wire connection data for the world. Each block position can have multiple conduit types with different connection states.

Canister

A container type for storing fluids, gases, or other substances. Defined in the CanistersCodex.

RAW

Raws And Wiki-syntax. A data definition format inspired by Dwarf Fortress, used for defining creature properties and other complex game data. See: Creature RAW

Tapestry

Decorative images that can be placed in the world as background art. See: Art Forgery

RGBA8888

A type alias for Int, representing a 32-bit colour value in RGBA format (8 bits per channel).

Cvec

Colour vector. A colour representation used for lighting calculations, supporting RGB plus UV (ultraviolet) channels.