# xaranaktu/fc-24-live-editor architecture

> Architecture diagram of the GitHub repository xaranaktu/fc-24-live-editor, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xaranaktu/fc-24-live-editor
- Repository: https://github.com/xaranaktu/fc-24-live-editor

## Overview

1. **What this repository is**
   - This is a Lua-based FC 24 “Live Editor” toolkit, not a traditional application server or website.
   - The repo is organized around three outputs: a reusable Lua library, a collection of one-off automation scripts, and packaged mods.

2. **Primary runtime boundary**
   - The code is meant to run in the context of the game/editor environment and interact with FC 24 game data directly.
   - The key architectural boundary is between **live game memory / squad data** and the **Lua tooling layer** that reads, edits, and exports changes.

3. **Core library layer**
   - `lua/libs/v2/imports/core` is the central foundation.
   - It includes low-level utilities such as memory access, logging, date helpers, shared constants, common helpers, player helpers, and a player manager.
   - `live_editor.lua` appears to be the main bridge into editor functionality.

4. **Game-domain modules**
   - The v2 imports are split by domain:
     - `career_mode` for manager/career-mode logic, enums, helpers, and user manager handling.
     - `gameplay` for gameplay-related managers like attribulator control.
     - `other` for miscellaneous constants/helpers/playstyle enums.
     - `services` for service-level enums and shared service definitions.
     - `aardvark` for a specific manager integration.
   - This separation suggests the library is structured as a set of feature-specific adapters over the core editor/memory layer.

5. **Database abstraction**
   - `lua/libs/v2/imports/t3db` provides a dedicated abstraction for database objects: `db.lua`, `table.lua`, and `field.lua`.
   - This is likely the boundary for editing squadfile-backed database tables, matching the README claim that only squadfile tables are editable.
   - The architecture therefore distinguishes **game memory editing** from **database/table editing**.

6. **External dependency handling**
   - `lua/libs/v2/imports/external/json.lua` shows that JSON parsing is vendored directly into the repo.
   - This means the library is designed to be self-contained rather than depending on an external package manager.

7. **Legacy compatibility**
   - `lua/libs/v1` contains an older `live_editor.lua` and documentation.
   - The repo maintains a v1/v2 split, indicating backward compatibility or an incremental migration path for scripts and integrations.

8. **Operational scripts**
   - `lua/scripts` is a large catalog of task-oriented automation scripts.
   - These are not reusable subsystems; they are end-user commands for concrete editor actions like:
     - modifying player attributes or appearance,
     - exporting season stats or transfer history,
     - generating minifaces,
     - fixing squads, contracts, nationality, or playstyles,
     - enabling/locking cosmetic or gameplay-related properties.
   - Architecturally, these scripts sit on top of the library and act as thin workflows.

9. **Data flow from library to scripts**
   - The usual flow is: **game state / database → core memory or T3DB layer → domain managers/helpers → script-specific mutation or export**.
   - Scripts likely compose the domain modules rather than reimplementing low-level access.
   - This makes the library the stable API surface and scripts the variable feature layer.

10. **Packaging and distribution**
   - `mods/` contains distributable zip packages with README files for specific gameplay or editor tweaks.
   - These are packaged artifacts rather than source modules, so they represent release outputs or curated bundles for users.
   - The presence of zipped mod packages indicates a separate distribution boundary from the Lua source tree.

11. **Testing and validation**
   - `lua/libs/v2/tests` contains focused tests for managers, event handlers, T3DB, plugins, and timing.
   - This suggests the library layer is the main unit-tested surface, especially around editor integrations and database abstractions.
   - The tests likely protect the reusable API, not the one-off scripts.

12. **Documentation and project support**
   - `README.md`, `changelog.txt`, `lua/DOC.MD`, and the per-module README files provide user-facing and developer-facing documentation.
   - The repo also references a wiki and release schedule, implying an ecosystem around the core tool rather than just source code.

13. **How to diagram the architecture**
   - A good diagram would show:
     - **FC 24 game/runtime** on one side,
     - **core memory + T3DB database access** as the integration layer,
     - **domain managers/helpers** above that,
     - **scripts** as feature entry points consuming the library,
     - **mods** as packaged outputs,
     - **tests/docs** as supporting assets around the codebase.

Main entry points: [`lua/libs/v2/main.lua`](https://github.com/xaranaktu/fc-24-live-editor/blob/main/lua/libs/v2/main.lua) (V2 entry), [`lua/libs/v2/imports/core/live_editor.lua`](https://github.com/xaranaktu/fc-24-live-editor/blob/main/lua/libs/v2/imports/core/live_editor.lua) (Editor bridge), [`lua/libs/v2/imports/core/memory.lua`](https://github.com/xaranaktu/fc-24-live-editor/blob/main/lua/libs/v2/imports/core/memory.lua) (Memory layer), [`lua/libs/v2/imports/t3db`](https://github.com/xaranaktu/fc-24-live-editor/tree/main/lua/libs/v2/imports/t3db) (T3DB layer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime boundary"]
  node_fc24_runtime(("FC 24 runtime<br/>game/editor host"))
end

subgraph group_v2core["V2 library"]
  node_core_memory["Memory layer<br/>memory access<br/>[memory.lua]"]
  node_core_live_editor["Editor bridge<br/>integration bridge<br/>[live_editor.lua]"]
  node_core_utils["Core utils<br/>shared helpers"]
  node_players_manager["Players manager<br/>player orchestration"]
  node_career_mode["Career mode<br/>domain adapters"]
  node_gameplay["Gameplay<br/>domain adapters"]
  node_other_domain["Other domain<br/>misc adapters"]
  node_services["Services<br/>service defs"]
  node_aardvark["Aardvark<br/>manager adapter"]
  node_t3db[("T3DB layer<br/>db abstraction")]
  node_external_json["JSON lib<br/>vendored dependency<br/>[json.lua]"]
  node_v2_main["V2 entry<br/>package entry<br/>[main.lua]"]
end

subgraph group_tooling["Tooling"]
  node_v1_legacy["V1 legacy<br/>legacy library<br/>[live_editor.lua]"]
  node_scripts["Scripts<br/>automation suite"]
  node_mods["Mods<br/>packaged outputs"]
  node_tests["Tests"]
  node_docs["Docs<br/>[README.md]"]
end

node_fc24_runtime -->|"live data"| node_core_memory
node_fc24_runtime -->|"squad tables"| node_t3db
node_core_memory -->|"bridge"| node_core_live_editor
node_core_memory -->|"shared support"| node_core_utils
node_core_utils -->|"player ops"| node_players_manager
node_core_memory -->|"read/write"| node_players_manager
node_core_live_editor -->|"domain API"| node_career_mode
node_core_live_editor -->|"domain API"| node_gameplay
node_core_live_editor -->|"domain API"| node_other_domain
node_core_live_editor -->|"service defs"| node_services
node_core_live_editor -->|"adapter"| node_aardvark
node_t3db -->|"parsing"| node_external_json
node_v2_main -->|"assembles"| node_core_live_editor
node_v2_main -->|"exports"| node_t3db
node_v2_main -->|"exports"| node_career_mode
node_v2_main -->|"exports"| node_gameplay
node_v2_main -->|"exports"| node_other_domain
node_v2_main -->|"exports"| node_services
node_v2_main -->|"exports"| node_aardvark
node_v1_legacy -.->|"compatibility path"| node_v2_main
node_scripts -->|"uses"| node_v2_main
node_scripts -->|"edit/export"| node_t3db
node_mods -.->|"bundles"| node_scripts
node_tests -->|"verifies"| node_v2_main
node_docs -.->|"documents"| node_v1_legacy
node_docs -.->|"documents"| node_v2_main

click node_core_memory "https://github.com/xaranaktu/fc-24-live-editor/blob/main/lua/libs/v2/imports/core/memory.lua"
click node_core_live_editor "https://github.com/xaranaktu/fc-24-live-editor/blob/main/lua/libs/v2/imports/core/live_editor.lua"
click node_core_utils "https://github.com/xaranaktu/fc-24-live-editor/tree/main/lua/libs/v2/imports/core"
click node_players_manager "https://github.com/xaranaktu/fc-24-live-editor/blob/main/lua/libs/v2/imports/core/managers/players_manager.lua"
click node_career_mode "https://github.com/xaranaktu/fc-24-live-editor/tree/main/lua/libs/v2/imports/career_mode"
click node_gameplay "https://github.com/xaranaktu/fc-24-live-editor/tree/main/lua/libs/v2/imports/gameplay"
click node_other_domain "https://github.com/xaranaktu/fc-24-live-editor/tree/main/lua/libs/v2/imports/other"
click node_services "https://github.com/xaranaktu/fc-24-live-editor/tree/main/lua/libs/v2/imports/services"
click node_aardvark "https://github.com/xaranaktu/fc-24-live-editor/blob/main/lua/libs/v2/imports/aardvark/aardvark_manager.lua"
click node_t3db "https://github.com/xaranaktu/fc-24-live-editor/tree/main/lua/libs/v2/imports/t3db"
click node_external_json "https://github.com/xaranaktu/fc-24-live-editor/blob/main/lua/libs/v2/imports/external/json.lua"
click node_v2_main "https://github.com/xaranaktu/fc-24-live-editor/blob/main/lua/libs/v2/main.lua"
click node_v1_legacy "https://github.com/xaranaktu/fc-24-live-editor/blob/main/lua/libs/v1/live_editor.lua"
click node_scripts "https://github.com/xaranaktu/fc-24-live-editor/tree/main/lua/scripts"
click node_mods "https://github.com/xaranaktu/fc-24-live-editor/tree/main/mods"
click node_tests "https://github.com/xaranaktu/fc-24-live-editor/tree/main/lua/libs/v2/tests"
click node_docs "https://github.com/xaranaktu/fc-24-live-editor/blob/main/README.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_fc24_runtime toneBlue
class node_core_memory,node_core_live_editor,node_core_utils,node_players_manager,node_career_mode,node_gameplay,node_other_domain,node_services,node_aardvark,node_t3db,node_external_json,node_v2_main toneAmber
class node_v1_legacy,node_scripts,node_mods,node_tests,node_docs toneMint
```

## Components

### Runtime boundary

FC 24 game/editor environment and the Lua tooling that operates on live data.

- **FC 24 runtime**: game/editor host · Live game/editor environment exposing memory and squad data to the tooling.

### V2 library

Reusable Lua library for memory, domain adapters, and database access.

- [Memory layer](https://github.com/xaranaktu/fc-24-live-editor/blob/main/lua/libs/v2/imports/core/memory.lua): memory access · Low-level access and shared runtime helpers for reading and mutating live data. · `lua/libs/v2/imports/core/memory.lua`
- [Editor bridge](https://github.com/xaranaktu/fc-24-live-editor/blob/main/lua/libs/v2/imports/core/live_editor.lua): integration bridge · Main bridge into editor functionality from the reusable library. · `lua/libs/v2/imports/core/live_editor.lua`
- [Core utils](https://github.com/xaranaktu/fc-24-live-editor/tree/main/lua/libs/v2/imports/core): shared helpers · Common constants, date helpers, logging, general helpers, and player helpers. · `lua/libs/v2/imports/core`
- [Players manager](https://github.com/xaranaktu/fc-24-live-editor/blob/main/lua/libs/v2/imports/core/managers/players_manager.lua): player orchestration · Higher-level player operations built on the core memory and helper layer. · `lua/libs/v2/imports/core/managers/players_manager.lua`
- [Career mode](https://github.com/xaranaktu/fc-24-live-editor/tree/main/lua/libs/v2/imports/career_mode): domain adapters · Manager/career-mode logic, enums, helpers, and user manager handling. · `lua/libs/v2/imports/career_mode`
- [Gameplay](https://github.com/xaranaktu/fc-24-live-editor/tree/main/lua/libs/v2/imports/gameplay): domain adapters · Gameplay-related managers such as attribulator control. · `lua/libs/v2/imports/gameplay`
- [Other domain](https://github.com/xaranaktu/fc-24-live-editor/tree/main/lua/libs/v2/imports/other): misc adapters · Miscellaneous constants, helpers, and playstyle enums. · `lua/libs/v2/imports/other`
- [Services](https://github.com/xaranaktu/fc-24-live-editor/tree/main/lua/libs/v2/imports/services): service defs · Service-level enums and shared service definitions. · `lua/libs/v2/imports/services`
- [Aardvark](https://github.com/xaranaktu/fc-24-live-editor/blob/main/lua/libs/v2/imports/aardvark/aardvark_manager.lua): manager adapter · Specific manager integration layer for an external or specialized feature. · `lua/libs/v2/imports/aardvark/aardvark_manager.lua`
- [T3DB layer](https://github.com/xaranaktu/fc-24-live-editor/tree/main/lua/libs/v2/imports/t3db): db abstraction · Database object abstraction for squadfile-backed tables and fields. · `lua/libs/v2/imports/t3db`
- [JSON lib](https://github.com/xaranaktu/fc-24-live-editor/blob/main/lua/libs/v2/imports/external/json.lua): vendored dependency · Vendored JSON parser used to keep the toolkit self-contained. · `lua/libs/v2/imports/external/json.lua`
- [V2 entry](https://github.com/xaranaktu/fc-24-live-editor/blob/main/lua/libs/v2/main.lua): package entry · Top-level v2 package entry point that assembles the reusable library. · `lua/libs/v2/main.lua`

### Tooling

One-off scripts, packaged mods, tests, and documentation.

- [V1 legacy](https://github.com/xaranaktu/fc-24-live-editor/blob/main/lua/libs/v1/live_editor.lua): legacy library · Older live editor implementation and documentation retained for compatibility. · `lua/libs/v1/live_editor.lua`
- [Scripts](https://github.com/xaranaktu/fc-24-live-editor/tree/main/lua/scripts): automation suite · One-off Lua workflows for editing, exporting, fixing, and generating game data. · `lua/scripts`
- [Mods](https://github.com/xaranaktu/fc-24-live-editor/tree/main/mods): packaged outputs · Distributable mod bundles and README files for curated tweaks. · `mods`
- [Tests](https://github.com/xaranaktu/fc-24-live-editor/tree/main/lua/libs/v2/tests): library tests · Focused tests covering managers, event handlers, T3DB, plugins, and timing. · `lua/libs/v2/tests`
- [Docs](https://github.com/xaranaktu/fc-24-live-editor/blob/main/README.md): project docs · Repository documentation and changelog material for users and contributors. · `README.md`

## Connections

- FC 24 runtime → Memory layer: live data · The host runtime exposes game memory and state to the core layer.
- FC 24 runtime → T3DB layer: squad tables · The host runtime provides the database-backed squad data manipulated by T3DB.
- Memory layer → Editor bridge: bridge · The memory layer feeds the main editor bridge.
- Memory layer → Core utils: shared support · Low-level access relies on shared constants and helper utilities.
- Core utils → Players manager: player ops · Player helpers and shared utilities support higher-level player management.
- Memory layer → Players manager: read/write · Player management composes the memory layer for direct edits.
- Editor bridge → Career mode: domain API · The editor bridge is specialized through career-mode adapters and managers.
- Editor bridge → Gameplay: domain API · Gameplay-specific operations hang off the shared editor bridge.
- Editor bridge → Other domain: domain API · Miscellaneous feature helpers extend the central editor bridge.
- Editor bridge → Services: service defs · Service enums and shared definitions support the higher-level integration surface.
- Editor bridge → Aardvark: adapter · Specialized integration for aardvark-style manager functionality.
- T3DB layer → JSON lib: parsing · JSON support is vendored for self-contained database tooling.
- V2 entry → Editor bridge: assembles · The v2 entry point wires together the core editor bridge.
- V2 entry → T3DB layer: exports · The package entry exposes the database abstraction layer.
- V2 entry → Career mode: exports · The package entry includes career-mode adapters.
- V2 entry → Gameplay: exports · The package entry includes gameplay managers.
- V2 entry → Other domain: exports · The package entry includes miscellaneous domain helpers.
- V2 entry → Services: exports · The package entry includes service definitions.
- V2 entry → Aardvark: exports · The package entry includes the aardvark integration.
- V1 legacy → V2 entry: compatibility path · The legacy library provides an older entry point alongside the v2 package.
- Scripts → V2 entry: uses · Automation scripts consume the reusable v2 library.
- Scripts → T3DB layer: edit/export · Many scripts operate directly on squadfile-backed database tables.
- Mods → Scripts: bundles · Packaged mods represent curated distributable outputs derived from tooling and scripts.
- Tests → V2 entry: verifies · Tests protect the reusable v2 library surface and integrations.
- Docs → V1 legacy: documents · Repository docs describe the legacy and current library split.
- Docs → V2 entry: documents · Documentation explains the current reusable library and its usage.
