# salinecitrine/noita-wand-simulator architecture

> Architecture diagram of the GitHub repository salinecitrine/noita-wand-simulator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/salinecitrine/noita-wand-simulator
- Repository: https://github.com/salinecitrine/noita-wand-simulator

## Overview

- UI Layer – Represented by the React components located in src/app/components (with specialized subdirectories for preset menus, wand actions, shared generic components, etc.). The entry point is src/app/App.tsx and public/index.html.
- Calculation / Simulation Engine – The “calc” directory (and its subdirectories such as eval and extra) contains the logic for computing wand behavior, shooting effects, and spell simulation. Treat this as the business logic or simulation module.
- State Management – The Redux components in src/app/redux (slices for wand, presets, configuration, etc.) handle application state, acting as the glue between UI events and the simulation engine.
- Code Generation Scripts – The Python scripts in the scripts/ folder (“generate_gun_actions.py”, “generate_entity_map.py”, “generate_translations.py”) generate parts of the Typescript code (e.g., spell functions, entity mappings, translations) that feed into the simulation engine. Even though these are development utilities, they form an important pre-runtime step.
- Static Public Assets – In the public/ directory, along with manifest and index.html. These are used for the browser deployment and possibly to host static data files (such as UI graphics or data used in the simulation).
- Testing & Utility Functions – The __tests__ directories scattered within the calc and util functions signifying unit tests ensuring calculation accuracy and proper utility function behavior.
- Local Storage – There is a localStorage.ts file, indicating that some state or configuration may be preserved locally between sessions.

##### Relationships and flows
- The Browser loads the static assets from public/ (index.html, manifest, etc.) to start the React app.
- The App (src/app/App.tsx) bootstraps the UI components, which in turn interact with the Redux store.
- The Redux store (in src/app/redux) receives UI events and triggers changes that can invoke calls to the Calculation Engine.
- The Calculation Engine, composed of various modules in src/app/calc (including eval and extra), processes simulation logic and returns results to the UI for display (such as wand shot results, spell visualizations, etc.).
- The Python scripts serve as pre-build code generators that ensure that parts of the simulation engine (such as gun actions and entity mappings) are kept in sync with the original Lua definitions and external translation CSV files.
- The testing components validate correctness at both the UI and simulation engine levels.

##### Architectural patterns and design principles
- A clear separation-of-concerns is seen: UI (React Components), Business Logic (Simulation and Calculation), and State Management (Redux).
- Code generation as a pre-processing step is a noteworthy pattern, ensuring that generated code remains synchronized with the original data sources.
- The project uses modular components and organizes them in directories reflecting their purpose (configuration, shot results, wand actions), facilitating clear component reuse.

## Diagram (Mermaid)

```mermaid
graph TD
    Browser["User's Browser"]:::runtime
    PublicAssets["Static Public Assets"]:::runtime
    Browser -->|"Loads"| PublicAssets

    subgraph "React App"
        AppEntry["App Entry Point (React, Typescript)"]:::runtime
        UIComponents["UI Components (src/app/components)"]:::runtime
        ReduxStore["Redux Store (Redux)"]:::runtime
    end
    PublicAssets -->|"InitialLoad"| AppEntry

    UIComponents <-->|"UIEvents"| ReduxStore

    subgraph "Calculation Engine"
        CalcModule["Calculation Module (src/app/calc)"]:::runtime
        EvalModule["Eval Module (src/app/calc/eval)"]:::runtime
        ExtraModule["Extra Module (src/app/calc/extra)"]:::runtime
        GunTs["gun.ts"]:::runtime
        GunEnums["gun_enums.ts"]:::runtime
        GunExtraModifiers["gun_extra_modifiers.ts"]:::runtime
        GunGenerated["gun_generated.ts"]:::runtime
        GunActionGenerated["gunaction_generated.ts"]:::runtime
        GunShotEffects["gunshoteffects_generated.ts"]:::runtime
    end

    ReduxStore -->|"TriggersCalc"| CalcModule
    CalcModule -->|"ReturnsResults"| UIComponents

    subgraph "Code Generation Tools"
        EntityMapGen["Entity Map Generator (Python)"]:::build
        GunActionsGen["Gun Actions Generator (Python)"]:::build
        TranslationsGen["Translations Generator (Python)"]:::build
    end
    EntityMapGen -->|"Generates"| CalcModule
    GunActionsGen -->|"Generates"| CalcModule
    TranslationsGen -->|"Generates"| CalcModule

    LocalStorage["Local Storage (src/app/localStorage.ts)"]:::runtime
    ReduxStore -->|"StoresState"| LocalStorage
    LocalStorage -->|"LoadsState"| ReduxStore

    subgraph "Testing & Utility"
        CalcTests["Calc Engine Tests (src/app/calc/__tests__)"]:::test
        UtilTests["Utility Tests (src/app/util/__tests__)"]:::test
    end
    CalcTests ---|"Validates"| CalcModule
    UtilTests ---|"Validates"| ReduxStore

    classDef runtime fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef build fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef test fill:#fff3cd,stroke:#856404,stroke-width:2px;

    click AppEntry "https://github.com/salinecitrine/noita-wand-simulator/blob/master/src/app/App.tsx"
    click UIComponents "https://github.com/salinecitrine/noita-wand-simulator/tree/master/src/app/components"
    click ReduxStore "https://github.com/salinecitrine/noita-wand-simulator/tree/master/src/app/redux"
    click CalcModule "https://github.com/salinecitrine/noita-wand-simulator/tree/master/src/app/calc"
    click EvalModule "https://github.com/salinecitrine/noita-wand-simulator/tree/master/src/app/calc/eval"
    click ExtraModule "https://github.com/salinecitrine/noita-wand-simulator/tree/master/src/app/calc/extra"
    click GunTs "https://github.com/salinecitrine/noita-wand-simulator/blob/master/src/app/calc/gun.ts"
    click GunEnums "https://github.com/salinecitrine/noita-wand-simulator/blob/master/src/app/calc/gun_enums.ts"
    click GunExtraModifiers "https://github.com/salinecitrine/noita-wand-simulator/blob/master/src/app/calc/gun_extra_modifiers.ts"
    click GunGenerated "https://github.com/salinecitrine/noita-wand-simulator/blob/master/src/app/calc/gun_generated.ts"
    click GunActionGenerated "https://github.com/salinecitrine/noita-wand-simulator/blob/master/src/app/calc/gunaction_generated.ts"
    click GunShotEffects "https://github.com/salinecitrine/noita-wand-simulator/blob/master/src/app/calc/gunshoteffects_generated.ts"
    click EntityMapGen "https://github.com/salinecitrine/noita-wand-simulator/blob/master/scripts/generate_entity_map.py"
    click GunActionsGen "https://github.com/salinecitrine/noita-wand-simulator/blob/master/scripts/generate_gun_actions.py"
    click TranslationsGen "https://github.com/salinecitrine/noita-wand-simulator/blob/master/scripts/generate_translations.py"
    click PublicAssets "https://github.com/salinecitrine/noita-wand-simulator/tree/master/public/"
    click CalcTests "https://github.com/salinecitrine/noita-wand-simulator/tree/master/src/app/calc/__tests__"
    click UtilTests "https://github.com/salinecitrine/noita-wand-simulator/tree/master/src/app/util/__tests__"
    click LocalStorage "https://github.com/salinecitrine/noita-wand-simulator/blob/master/src/app/localStorage.ts"
```
