mirror of
https://github.com/mleem97/gregWiki.git
synced 2026-04-11 03:29:19 +02:00
docs: update docusaurus configuration and documentation structure
- Revised the tagline in `docusaurus.config.js` for improved clarity on the documentation's focus. - Removed German localization support from the configuration to streamline the user experience. - Updated navigation items in the sidebar to better reflect the current structure, emphasizing player and developer resources. - Enhanced the README and various documentation files to clarify the repository layout and improve accessibility for users. - Adjusted links and descriptions throughout the documentation to ensure consistency and accuracy. This commit aims to enhance the overall clarity and usability of the documentation.
This commit is contained in:
67
docs/meta/system-architecture-principles.md
Normal file
67
docs/meta/system-architecture-principles.md
Normal file
@@ -0,0 +1,67 @@
|
||||
---
|
||||
title: System architecture & documentation principles
|
||||
sidebar_label: Architecture principles
|
||||
description: Canonical stack model (ModManager → Framework → Plugins → Mods), priorities, and how wiki pages should align.
|
||||
---
|
||||
|
||||
# System architecture & documentation principles
|
||||
|
||||
This page is the **canonical reference** for how gregFramework documentation describes the stack: **ModManager (MAUI) → modding framework / SDK → plugins → mods**, plus priorities (stability first), the hook-proxy idea, and **authoring rules**. All wiki content must be written in **English** only.
|
||||
|
||||
Detail pages (individual mods, plugins, releases) should align with this model without repeating the full narrative each time — **link here** for the big picture.
|
||||
|
||||
## Layer model (target architecture)
|
||||
|
||||
Describe the runtime as a **layered system**, not a flat list of DLLs:
|
||||
|
||||
| Layer | Role | Typical workspace artifacts |
|
||||
|--------|--------|------------------------------|
|
||||
| **1. ModManager (front-end)** | UI to enable/disable mods and plugins, ordering, configuration, game state (e.g. no save loaded, level loading). Talks to the framework through **well-defined** interfaces (shared library, config files, IPC, named pipes, HTTP — depending on implementation). | `gregModmanager/` — **Gregtools Modmanager** (MAUI, e.g. `WorkshopUploader.csproj`). |
|
||||
| **2. Modding framework / SDK** | Stable API surface for plugins and mods: lifecycle, events, versioning, dependencies, logging, error handling. Hooks Unity / MelonLoader / IL2CPP and **maps** low-level events to **framework events** (hook proxy). | `gregCore/` — e.g. `FrikaMF`, Harmony integration, bridges (e.g. Rust), hook registry. |
|
||||
| **3. Plugins** | Extend the framework (new services, hook types, optional ModManager UI). Clear extension points. | `FFM.Plugin.*`, repos **`gregExt.<Name>/`**. |
|
||||
| **4. Mods** | User extensions via the **documented** framework API; avoid direct IL2CPP details where possible; load in isolation; soft-fail on errors. | `FMF.*`, repos **`gregMod.<Name>/`**. |
|
||||
|
||||
**Mnemonic:** `ModManager → Framework → Plugins → Mods`.
|
||||
|
||||
### Hook proxy and hotloading (concept)
|
||||
|
||||
- The framework should map **Unity / IL2CPP events** (MelonLoader hooks, patches) to **stable, named framework events** (e.g. level loaded, scene changed, update) so mods do not couple to concrete Unity signatures.
|
||||
- **Hotloading** mods is a target state: load only in **safe** states (e.g. no active save, menu), re-bind on level change — exact rules live in framework code and should appear in technical articles **only** when anchored in the repo.
|
||||
|
||||
These wiki pages do **not** mandate a specific implementation; they **align** authors and readers on the same vocabulary.
|
||||
|
||||
## Technical context (expertise areas)
|
||||
|
||||
Documentation and reviews in the gregFramework space typically assume:
|
||||
|
||||
- **C# / .NET** (modern language features, best practices)
|
||||
- **Unity with IL2CPP**
|
||||
- **MelonLoader** and modular **FMF** / **FFM** stacks
|
||||
- **.NET MAUI** for the ModManager (deployment, installer, release vs debug issues)
|
||||
- Debugging, logging, tracing, crash analysis (including outside the IDE)
|
||||
|
||||
## Priorities (when trade-offs arise)
|
||||
|
||||
When documentation or API design must choose, use this **order**:
|
||||
|
||||
1. **Stability and fault tolerance** — faulty mods must not tear down the whole system arbitrarily; clear error paths and logging.
|
||||
2. **Clean architecture and maintainability** — clear layers, documented interfaces.
|
||||
3. **Developer experience** — understandable APIs, hooks, logging for mod authors.
|
||||
4. **Performance and low invasiveness** toward the game.
|
||||
5. **Extensibility and long-term compatibility** — versioning, dependency rules.
|
||||
|
||||
## Rules for wiki authors
|
||||
|
||||
- **Terminology:** Always name the layer (ModManager, framework, plugin, mod). Do not conflate “plugin” and “mod” without context.
|
||||
- **Language:** **English only** for all user-facing documentation in `docs/`, the homepage, and UI strings in this site.
|
||||
- **Repos:** Keep paths such as `gregCore/`, `gregMod.*`, `gregExt.*`, `gregModmanager/` consistent with the [Workspace map](/wiki/workspace) and [Repository architecture](/wiki/framework/architecture).
|
||||
- **No invented APIs:** New pages must not promise hooks or events that are not evidenced in core/registry — link to [FMF hooks](/wiki/framework/fmf-hooks) and the [Hooks catalog](/wiki/reference/fmf-hooks-catalog).
|
||||
- **Cross-links:** Entry [Developers & contributors](/wiki/developers), architecture [Repository architecture](/wiki/framework/architecture), language rule [Modding language (C# only)](/wiki/reference/modding-language-requirement).
|
||||
|
||||
## See also
|
||||
|
||||
- [Repository architecture](/wiki/framework/architecture) — multi-repo layout, core, bridges
|
||||
- [Getting started](/wiki/getting-started) — workspace and build
|
||||
- [Mods — Framework](/wiki/mods/framework) — runtime from mod authors’ perspective
|
||||
- [Plugins overview](/wiki/plugins/) — `FFM.Plugin.*`
|
||||
- [Mod developers](/wiki/guides/mod-developers/overview)
|
||||
Reference in New Issue
Block a user