# jodli/creativemod architecture

> Architecture diagram of the GitHub repository jodli/creativemod, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-02-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jodli/creativemod
- Repository: https://github.com/jodli/creativemod

## Overview

##### Main Components
- Mod Core & Initialization:
- control.lua sits at the root and is responsible for initializing and managing mod lifecycle events.
- settings.lua, defines.lua, info.json, and version-history.txt contain configuration and meta-information.
- Prototypes:
- The “prototypes” directory includes files detailing new entities, items, recipes, technologies, and styles. This represents the custom gameplay content that the mod adds.
- Scripts & Logic:
- The “scripts” directory contains various Lua scripts that implement mod functionality such as “creative chest,” “magic wand” actions, custom events, GUI interactions, and utility functions. These scripts manage gameplay logic and event handling.
- Graphics:
- Localization:
- The “locale” directory houses language files (e.g., English, Chinese variants) that ensure the mod is internationalized.
- Migrations & Configuration:
- The “migrations” directory contains scripts and JSON files to support mod version upgrades, ensuring backward compatibility.
- CI/CD and Version Control:
- The “.github” folder (with its workflows and release configuration) illustrates integration with GitHub Actions for automated testing, releases, or builds.
- Documentation & Licensing:
- Files like README.md, license.txt, and changelog.txt provide context, documentation, and legal information important for both developers and users.

##### Relationships and Interactions
- Initialization Flow:
- At game start-up (or mod initialization), Factorio loads control.lua which sets up event listeners and utility configurations.
- control.lua interacts with scripts in the “scripts” folder to trigger gameplay events.
- Prototypes Integration:
- The “prototypes” components register custom entities, items, and recipes with the game, which the scripts then manipulate as required.
- Visual and UX Linkage:
- The scripts that handle GUI (e.g., files inside scripts/gui*.lua) utilize the asset files in the “graphics” directory to form the mod’s frontend elements.
- Localization and Mod Compatibility:
- Language-specific files from “locale” provide the textual content for tooltips, labels, and menus.
- The mod is built with compatibility in mind so that its features integrate smoothly with other Factorio mods, an aspect mentioned in the README.
- Build and Release Pipeline:
- The GitHub workflows (in .github/workflows) point to continuous integration (CI) practices that ensure that any updates are automatically tested and released.

##### Architectural Patterns and Design Principles
- Separation of Concerns:
- Code is categorized into prototypes (defining gameplay entities) and scripts (handling logic and behavior), keeping responsibilities distinct.
- Event-Driven Programming:
- The mod likely leverages Factorio's event model (e.g., event registration in control.lua and scripts/events.lua) to respond to gameplay actions.
- Modularity and Extensibility:
- With separate directories for scripts and prototypes, the mod is designed in a modular manner, making it easier to add or modify functionality.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Factorio Mod Architecture"
        CICD["CI/CD Pipeline\n(GitHub Actions)"]:::cicd
        Init["Mod Core & Initialization\n(control.lua, settings.lua, defines.lua, info.json, version-history.txt)"]:::modCore
        Proto["Prototypes Registration\n(prototypes/)"]:::prototypes
        Scripts["Game Logic & Scripts\n(scripts/)"]:::scripts
        Graphics["GUI & Graphics Assets\n(graphics/)"]:::graphics
        Locale["Localization Files\n(locale/)"]:::locale
        Migrations["Migrations & Configuration\n(migrations/)"]:::migrations
        Docs["Documentation & Licensing\n(README.md, license.txt, changelog.txt)"]:::docs
    end

    CICD -->|"CItrigger"| Init
    Init -->|"initTriggers"| Scripts
    Init -->|"registers"| Proto
    Proto -->|"providesEntities"| Scripts
    Scripts -->|"usesAssets"| Graphics
    Scripts -->|"usesLocale"| Locale
    Migrations -->|"versionUpgrade"| Init

    %% Legend
    subgraph "Legend"
        L1["Rectangle: Code Module / Directory"]
        L2["Cylinders: Not used"]
        L3["Cloud: External process (CI/CD)"]
    end

    %% Click Events
    click Init "https://github.com/jodli/creativemod/blob/master/control.lua"
    click Proto "https://github.com/jodli/creativemod/tree/master/prototypes/"
    click Scripts "https://github.com/jodli/creativemod/tree/master/scripts/"
    click Graphics "https://github.com/jodli/creativemod/tree/master/graphics/"
    click Locale "https://github.com/jodli/creativemod/tree/master/locale/"
    click Migrations "https://github.com/jodli/creativemod/tree/master/migrations/"
    click CICD "https://github.com/jodli/creativemod/tree/master/.github/"
    click Docs "https://github.com/jodli/creativemod/blob/master/README.md"

    %% Styles
    classDef modCore fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef prototypes fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef scripts fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef graphics fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef locale fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
    classDef migrations fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef cicd fill:#fefefe,stroke:#333,stroke-width:2px;
    classDef docs fill:#fefefe,stroke:#333,stroke-width:2px;
```
