DOCSEARCHbyAlgolia
Submit Docs

LearnMindustryMod Documentation

website·Indexed 30 days ago

https://learn-mindustry-mod.github.io/

A comprehensive guide for Mindustry modding, covering game content creation (items, fluids, units, and blocks), Java and Kotlin programming fundamentals, and advanced graphics using OpenGL. It includes detailed technical explanations on the game's rendering pipeline, shaders, FrameBuffers, and the compile-time ECS architecture, as well as reference tables for events, triggers, and block types.

Tokens
115.4K
Snippets
447
Records
688
Agent score
75%

What's inside LearnMindustryMod

  1. Overview of Mindustry Data Patches (DP)

    Data Patches (DP), formerly known as Content Patches, allow developers to modify existing fields of objects (blocks, units, items, liquids, statuses, weather, etc.) in the base game or other mods using Hjson/JSON files.

    Best used for:

    • Balance patches (damage, health, cost, production time).
    • Custom game modes (weaponry, recipes, ammo).
    • Map or server-specific rules.
    • Modifying textures, display names, and icons.

    Limitations:

    • Cannot add entirely new game mechanisms.
    • Cannot change the type of a block (e.g., turning a wall into a turret).
    • Cannot rewrite Java initialization logic.
    • Some derived values (calculated from other fields) may not update automatically.

  2. Overview of the Mindustry Modding Learning Path

    This tutorial provides a structured approach to Mindustry mod development, moving from basic setup to advanced systems. The curriculum is divided into the following stages:

    1. Mod Development Environment & Deployment: Setting up the basic development environment.
    2. Creating Game Content: Initial content creation (similar to JSON-based mods).
    3. Program Logic for Game Content: Understanding the programming principles behind game content.
    4. Debugging: Using tools to resolve unexpected program behavior.
    5. Drawing & Animation: Utilizing built-in game tools for graphics and animations.
    6. Graphical User Interface (GUI) Programming: Creating interactive user interfaces using GUI components.
    7. Program Architecture: Deep dive into the game's underlying architecture and logic.
    8. Advanced Graphical Effects: Using OpenGL for high-end rendering effects.

  3. Overview of Mindustry's Compile-Time ECS Architecture

    Mindustry utilizes a compile-time ECS (Entity Component System) architecture to replace traditional deep inheritance hierarchies. By using annotation processors, the engine generates core system code during compilation, converting dynamic runtime behaviors into static optimizations. This separates data and behavior, improving extensibility and CPU cache efficiency.

  4. Overview of Mindustry JSON Modding Guide (DeepSeek Edition)

    This guide provides a systematic approach to creating JSON-based mods for Mindustry. It focuses on teaching developers how to read Java source code to identify the correct fields, types, and behaviors required to achieve specific modding effects. The guide is based on the v8 main line source code of Mindustry and Arc, using the 'Saturated Fire' (饱和火力) mod as a primary structural reference for block and item definitions.

  5. Overview of Mindustry Power System

    The power system in Mindustry consists of four primary components: Generators (produce power), PowerNodes (transmit power), Batteries (store power), and PowerModules (consume power). The PowerGraph handles the scheduling and distribution of electricity across the network.

  6. Overview of Mindustry's Compile-time ECS Architecture

    Mindustry uses a specialized Entity Component System (ECS) where the composition of entities is handled at compile-time via a code generator (annotation processor). Unlike traditional ECS that look up components at runtime (which can cause cache misses and performance loss), Mindustry's approach hard-codes type relationships into generated classes to maximize performance in a high-entity-count game environment.

  7. Overview of Mindustry's Compile-time ECS Architecture

    Mindustry uses a compile-time ECS where entity capabilities are split into *Comp components. An annotation processor then assembles these components into final entity classes during compilation. Developers write 'recipes' in core/src/mindustry/entities/comp/*.java, but the game instantiates generated classes found in mindustry.gen.*.

  8. Overview of Block lifecycle methods

    The Block class provides several key methods for customization:

    • init(): Called after all content is loaded. Use this to assign default values to fields.
    • load(): Called after initialization. Use this to fetch TextureRegion references from Core.atlas.
    • setStats(): Called when the core database for the block is opened. Use this to populate the stats map.
    • setBars(): Called during initialization. Use addBar<T extends Building>(String, Func<T, Bar>) to add progress bars.
    • drawPlace(int x, int y, int rotation, boolean isValid): (Desktop only) Defines what is drawn when a player selects the block in the build menu before placing it.

  9. Overview of Mindustry's Compile-time ECS Architecture

    Mindustry uses a 'Recipe + Factory' pattern for its Entity Component System (ECS). Instead of writing full entity classes, developers define component classes (ending in Comp) and entity definitions. An annotation processor then merges these components at compile-time to generate the final executable entity classes. This approach reduces code redundancy, simplifies network synchronization, and centralizes group management.

  10. Understand the Mindustry Event System

    Mindustry's event system is based on arc.Events. It consists of two primary types of notifications:

    1. Event Classes (EventType): Data-carrying notifications. These provide an event object containing parameters (e.g., which block was built, which unit was damaged).
    2. Triggers (EventType.Trigger): Parameterless signals. These are simple enum values used for high-frequency or lightweight notifications (e.g., frame updates, UI triggers).

    Both are registered using Events.on(...) and fired using Events.fire(...).

    Critical Constraints:

    • Threading: Event callbacks almost always execute on the main thread. Do not perform blocking operations inside an event listener. Use background threads for heavy work and Core.app.post(...) to return to the main thread for UI or game state updates.
    • Recursion: Avoid modifying tiles or triggering new tile-change operations within tile-related event listeners to prevent recursion or crashes.
    import arc.Events;
import mindustry.game.EventType;

// Listening to a data-carrying event
Events.on(EventType.BlockBuildEndEvent.class, e -> {
    if(!e.breaking){
        // Safely access e.tile, e.team, e.unit, e.config
    }
});

// Listening to a parameterless trigger
Events.on(EventType.Trigger.update, () -> {
    // Executes every frame; avoid heavy logic here
});

  11. Understand the Mindustry Consume system

    The Consume system manages resource consumption, efficiency, and statistics for blocks. It supports three modes: required, optional, and booster. A block's operational state is determined by its efficiency (typically 0 to 1); if efficiency falls below a tiny threshold, the block is considered inactive and displays a red status indicator.

    Consumers are stateless components (following a System pattern in ECS), meaning a single Consume instance is shared across all buildings of that block type. Interaction occurs by passing the Building instance as a parameter to the consumer's methods.

  12. Understand FrameBuffer and Off-screen Rendering

    Off-screen rendering allows developers to perform intermediate image processing before outputting the final result to the screen. In OpenGL (via the arc library), this is achieved using a FrameBuffer.

    A FrameBuffer simulates the standard frame structure (which consists of a ColorBuffer, DepthBuffer, and StencilBuffer) in a separate memory area. Instead of rendering directly to the screen (the default ScreenBuffer), rendering operations are directed to the currently bound FrameBuffer.