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.

Developer Portal

This is a place for developers, a hub for documentation and code conventions for the Terrarum game engine.

Getting Started

Glossary — Essential terminology and concepts
Modules — Understanding the module system
Modules:Setup — Setting up your first module

Core Engine Systems

Game World

World — World structure, chunks, and layers
Actors — The actor system and lifecycle
Inventory — Items and inventory management
Save and Load — Serialisation and persistence

Rendering

Rendering Pipeline — Graphics system and tile rendering
Lighting Engine — Lighting and shading simulation
OpenGL Considerations — GL 3.2 requirements and shader syntax

Physics

Physics Engine — AABB collision and Newtonian simulation

Audio

Audio System — Sound, music, and spatial audio

User Interface

UI Framework — Canvas-based UI system and components

Internationalisation and Localisation

Languages — Translation system and multilingual support
Keyboard Layout and IME — Input methods for complex scripts

Engine Internals (For Maintainers)

Advanced technical documentation for engine developers:

Build & Distribution

Building the App — Packaging for all platforms, custom JVM runtimes, and build scripts
Asset Archiving — TEVD archive format, build pipeline, and runtime loading

Rendering & Graphics

Tile Atlas System — Six-season atlas generation, subtiling, and dynamic texture management
Autotiling In-Depth — Connection algorithms, lookup tables, and subtiling patterns

Audio

Audio Engine Internals — Mixer architecture, DSP pipeline, spatial audio, and streaming

Coming Soon

Fluid Simulation Internals — Cellular automata and flow algorithms
Lighting Engine — RGB+UV light propagation and transmittance
Save Format Specification — TerranVirtualDisk binary format details
Physics Internals — AABB collision resolution and spatial partitioning
Networking — Multiplayer synchronisation and packet protocol

Making Modules

Content Creation

My Little Dagger — Creating custom items
My Precious Block — Creating custom blocks
Let It Snow — Custom weather systems
Art Forgery — Adding decorative images
Let There Be Non-Stationary Thingies — Creating custom actors
Texture Packs — Retexturing existing content

Advanced Topics

Items in-depth — Advanced item implementation
Actors in-depth — Deep dive into actor systems
Creature RAW — Data-driven creature definitions
Faction — Faction system and relationships

Engine Architecture

Core Components

App.java — Application entry point and initialisation
Terrarum.kt — Engine singleton and codex management
IngameInstance.kt — Base class for game screens
ModMgr.kt — Module loading and management

Code Organisation

src/net/torvald/terrarum/
├── gameactors/       # Actor system
├── gameworld/        # World structure
├── gameitems/        # Item system
├── blockproperties/  # Block definitions
├── itemproperties/   # Item properties
├── worlddrawer/      # Rendering
├── audio/            # Audio system
├── ui/               # User interface
├── serialise/        # Save/load
├── savegame/         # Virtual disk
├── langpack/         # Localisation
├── gamecontroller/   # Input handling
├── modulebasegame/   # Base game implementation
└── shaders/          # GLSL shaders

Data Structures

Codices

Codices are global registries for game content:

BlockCodex — All blocks and terrain types
ItemCodex — All items
WireCodex — Wire and conduit types
MaterialCodex — Material definitions
FactionCodex — Faction data
CraftingCodex — Crafting recipes
AudioCodex — Audio assets
WeatherCodex — Weather types
FluidCodex — Fluid properties
OreCodex — Ore definitions

Key Data Types

ActorID — Integer identifier for actors
ItemID — String identifier for items (item@module:id)
BlockAddress — Long integer for block positions
RGBA8888 — 32-bit colour value
Cvec — Colour vector with RGBUV channels

Rendering Details

Tile Atlas Formats

16×16 — Single tile, no autotiling
64×16 — Wall stickers (4 variants)
128×16 — Platforms (8 variants)
112×112 — Full autotiling (49 variants)
224×224 — Seasonal autotiling (4 seasons)

Render Order Layers

FAR_BEHIND — Wires and conduits
BEHIND — Tapestries, background particles
MIDDLE — Actors (players, NPCs, creatures)
MIDTOP — Projectiles, thrown items
FRONT — Front walls and barriers
OVERLAY — Screen overlays (unaffected by lighting)

Lighting System

RGB+UV — Four independent light channels
Transmittance — Light propagation through blocks
Dynamic lights — Time-varying luminosity functions
Corner occlusion — Shader-based depth enhancement

Physics Constants

TILE_SIZE — 16 pixels (configurable at compile time)
METER — 25 pixels (1 metre in game units)
PHYS_TIME_FRAME — 25.0 (physics time step)
PHYS_REF_FPS — 60.0 (reference frame rate)

Input Handling

Keyboard Layouts

Low Layer — Base layout (QWERTY, Colemak, etc.)
High Layer — Language-specific IME (Hangul, Kana, etc.)

Keyboard layouts are stored in assets/keylayout/ as .key files (Low Layer) and .ime files (High Layer).

Controller Support

GDX controllers (via LibGDX)
XInput devices (via JXInput)
Custom controller mappings

Modding API Guidelines

Module Structure

<module>/
├── metadata.properties    # Required: module info
├── default.json          # Optional: default config
├── icon.png             # Optional: 48×48 icon
├── <module>.jar         # Optional: compiled code
├── blocks/              # Block definitions
│   └── blocks.csv
├── items/               # Item definitions
│   └── itemid.csv
├── materials/           # Material definitions
│   └── materials.csv
├── locales/             # Translations
│   ├── en/
│   ├── koKR/
│   └── ...
├── crafting/            # Crafting recipes
│   └── *.json
└── retextures/          # Texture packs
    └── ...

Entry Point

If your module has a JAR file, create an entry point:

class MyModuleEntryPoint : ModuleEntryPoint() {
    override fun init() {
        // Load blocks
        ModMgr.GameBlockLoader.loadAll(moduleInfo)

        // Load items
        ModMgr.GameItemLoader.loadAll(moduleInfo)

        // Load materials
        ModMgr.GameMaterialLoader.loadAll(moduleInfo)

        // Load languages
        ModMgr.GameLanguageLoader.loadAll(moduleInfo)

        // Load crafting recipes
        ModMgr.GameCraftingRecipeLoader.loadAll(moduleInfo)
    }
}

Dependency Management

Specify module dependencies in metadata.properties:

dependency=basegame 0.4.0+;othermod 1.2.*

Version syntax:

a.b.c — Exact version
a.b.c+ — Version a.b.c to a.b.65535
a.b.* — Any version a.b.x
a.b+ — Version a.b.0 to a.255.65535
a.* — Any version a.x.x
* — Any version (testing only!)

Code Conventions

Naming

Classes — PascalCase (ActorPlayer, BlockStone)
Functions — camelCase (update, getTileFromTerrain)
Constants — SCREAMING_SNAKE_CASE (TILE_SIZE, METER)
Properties — camelCase (hitbox, baseMass)

Language Usage

Kotlin — Preferred for new game logic and systems
Java — Used for performance-critical code and LibGDX integration
Comments — Required for public APIs

File Organisation

One public class per file
Filename matches class name
Group related classes in packages

Asset Guidelines

Image Formats

With transparency — Export as TGA
Without transparency — Export as PNG
Colour space — sRGB, white point D65

Audio Formats

Music — OGG Vorbis, -q 10 quality
SFX — OGG Vorbis or WAV
Sample rate — 44100 Hz

Text Files

Encoding — UTF-8
Line endings — Unix (LF)
JSON — Properly formatted with indentation

Debugging Tools

Console Commands

Access the in-game console (typically F12) for:

Spawning items and actors
Teleportation
Time manipulation
Debug overlays

Debug Flags

App.IS_DEVELOPMENT_BUILD = true  // Enable debug features

Debug features include:

Hitbox visualisation
Performance metrics
Verbose logging
Collision testing modes

Logging

import net.torvald.terrarum.App.printdbg

printdbg(this, "Debug message")
printdbgerr(this, "Error message")

Performance Profiling

DebugTimers

DebugTimers.start("MyOperation")
// ... code to profile
DebugTimers.end("MyOperation")

View results in the debug UI or logs.

Memory Monitoring

Java heap — Standard JVM memory
Unsafe allocation — Custom memory management
Texture memory — GPU texture usage

Testing

Manual Testing

Test with multiple modules loaded
Test module loading/unloading
Verify save/load compatibility
Check language switching
Test at different resolutions

Asset Validation

Check for missing textures
Verify audio file integrity
Test all translations
Validate JSON syntax

Common Pitfalls

Forgetting @Transient — Sprites and UI cannot serialise
Not calling reload() — Transient fields stay null
Hardcoding TILE_SIZE — Use the constant
Ignoring frame rate — Scale by delta time
Creating circular references — Breaks serialisation
Not disposing resources — Memory leaks
Assuming English — Support all languages

Best Practises

Follow existing patterns — Check neighbouring code
Document public APIs — Help other developers
Test with base game — Ensure compatibility
Handle missing data gracefully — Don't crash on errors
Provide fallbacks — Always have English translations
Version your content — Use semver strictly
Profile performance — Identify bottlenecks early

External Resources

Child Repositories

Terrarum Sans Bitmap — The font used in this game
TerranVirtualDisk — File archival format used in saves

Libraries

LibGDX — Game framework
LWJGL3 — OpenGL bindings
dyn4j — Physics library (for Vector2)
GraalVM JavaScript — Scripting engine

Documentation

Sample Projects

Terrarum Sample Module — Template for creating modules

Getting Help

Check this documentation portal
Review sample module code
Search existing modules for examples
Open an issue on GitHub for bugs
Join the community for questions

Happy modding!