docs: add arma-server-web-admin analysis reference docs
Brings in ANALYSIS.md, HOW_IT_WORKS.md, and CHERRY_PICK.md generated from deep analysis of the arma-server-web-admin benchmark project. These docs inform the Arma 3 UX enhancement plan (.claude/plan/arma3-ux-enhancement.md) and provide context for implementing agents without needing to re-read the source project.
This commit is contained in:
Khoa (Revenovich) Tran Gia
155
docs/ANALYSIS.md
Normal file
155
docs/ANALYSIS.md
Normal file
@@ -0,0 +1,155 @@
|
||||
# Arma Server Web Admin — Full Analysis
|
||||
|
||||
## Project Overview
|
||||
|
||||
**Arma Server Web Admin** is a Node.js/Express web application providing a browser-based administration panel for managing one or more Arma game server instances (Arma 1/2/2OA/3, CWA, OFP).
|
||||
|
||||
It consolidates all day-to-day server management tasks into a single UI:
|
||||
- Launch and stop game server processes
|
||||
- Monitor live player counts, current mission, and server state
|
||||
- Upload and rotate missions (.pbo files, including Steam Workshop)
|
||||
- Discover and assign mods per server
|
||||
- Browse and download server log files
|
||||
- Configure every server setting (ports, passwords, difficulty, mods, MOTD, etc.)
|
||||
- Deploy headless clients automatically alongside the server process
|
||||
|
||||
---
|
||||
|
||||
## Technology Stack
|
||||
|
||||
| Layer | Technology |
|
||||
|-------|-----------|
|
||||
| HTTP server | Node.js + Express.js |
|
||||
| Real-time | Socket.IO 2.x |
|
||||
| Game process | arma-server (Node wrapper) |
|
||||
| Game query | Gamedig |
|
||||
| Steam Workshop | steam-workshop |
|
||||
| File helpers | fs.extra, glob, multer |
|
||||
| Async control | async 2.x |
|
||||
| Frontend SPA | Backbone.js + Marionette.js |
|
||||
| Templating | Underscore.js |
|
||||
| UI framework | Bootstrap 3 |
|
||||
| Build | Webpack v1 |
|
||||
| Auth | express-basic-auth (optional) |
|
||||
|
||||
---
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
arma-server-web-admin/
|
||||
├── app.js # Entry point: Express + Socket.IO + route wiring
|
||||
├── config.js.example # All configuration options with defaults
|
||||
├── config.docker.js # Docker-specific config overrides
|
||||
├── webpack.config.js # Frontend bundling
|
||||
├── package.json
|
||||
│
|
||||
├── lib/ # Backend business logic
|
||||
│ ├── manager.js # Multi-server lifecycle manager (EventEmitter)
|
||||
│ ├── server.js # Single server wrapper (start/stop/query/persist)
|
||||
│ ├── missions.js # Mission file discovery, upload, Workshop download
|
||||
│ ├── logs.js # Log file discovery, cleanup, platform paths
|
||||
│ ├── settings.js # Config accessor (public subset for client)
|
||||
│ ├── setup-basic-auth.js # Optional HTTP Basic Auth middleware
|
||||
│ └── mods/
|
||||
│ ├── index.js # Mod discovery + parallel metadata resolution
|
||||
│ ├── folderSize.js # Recursive folder size calculator
|
||||
│ ├── modFile.js # Parses mod.cpp for display name
|
||||
│ └── steamMeta.js # Parses meta.cpp for Steam Workshop ID
|
||||
│
|
||||
├── routes/ # Express routers (each returns a router factory)
|
||||
│ ├── servers.js # /api/servers/* (CRUD + start/stop)
|
||||
│ ├── missions.js # /api/missions/* (list/upload/download/delete)
|
||||
│ ├── mods.js # /api/mods/* (list/delete)
|
||||
│ ├── logs.js # /api/logs/* (list/view/download/delete)
|
||||
│ └── settings.js # /api/settings (GET public settings)
|
||||
│
|
||||
└── public/ # Single-page frontend (built by Webpack)
|
||||
├── index.html
|
||||
├── css/styles.css
|
||||
└── js/
|
||||
├── app.js # RequireJS bootstrap + Socket.IO init
|
||||
└── app/
|
||||
├── router.js # Backbone Router (5 routes)
|
||||
├── models/ # Backbone Models
|
||||
├── collections/ # Backbone Collections
|
||||
└── views/ # Marionette views
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Feature Inventory
|
||||
|
||||
### Server Lifecycle
|
||||
- Create / edit / delete server definitions persisted to `servers.json`
|
||||
- Start / stop server processes (Windows `.exe`, Linux binary, Wine)
|
||||
- Auto-start servers on application launch (`auto_start` flag)
|
||||
- Process ID tracking
|
||||
- 5-second polling via Gamedig for live state (players, mission, status)
|
||||
|
||||
### Configuration
|
||||
- Title, port, max players
|
||||
- Player password, admin password
|
||||
- Message of the Day (MOTD, multi-line)
|
||||
- BattleEye, VoN, signature verification, file patching, persistent mode
|
||||
- Difficulty override (Recruit / Regular / Veteran / Custom)
|
||||
- Per-server additional `server.cfg` text (freeform)
|
||||
- Per-server startup parameters (e.g. `-limitFPS=100`)
|
||||
- Per-server mod selection
|
||||
- Per-server mission rotation with per-mission difficulty
|
||||
|
||||
### Mission Management
|
||||
- List `.pbo` files from `mpmissions/`
|
||||
- Upload up to 64 `.pbo` files at once (multipart)
|
||||
- Download from Steam Workshop by ID
|
||||
- Download mission files to browser
|
||||
- Delete mission files
|
||||
- View name, world name, file size, timestamps
|
||||
|
||||
### Mod Management
|
||||
- Auto-discover mods via glob patterns (`@*`, `csla`, `ef`, etc.)
|
||||
- Extract display name from `mod.cpp`
|
||||
- Extract Steam Workshop ID from `meta.cpp`
|
||||
- Calculate folder sizes recursively (symlink-aware)
|
||||
- Delete mod folders
|
||||
- Assign mods per server (split-pane UI)
|
||||
|
||||
### Log Management
|
||||
- Discover `.rpt` log files from platform-appropriate paths:
|
||||
- **Windows:** `AppData\Local\[Game]\`
|
||||
- **Linux:** `[game_path]/logs/`
|
||||
- **Wine:** `.wine/drive_c/users/.../Application Data/[Game]/`
|
||||
- View log contents inline
|
||||
- Download logs
|
||||
- Delete logs
|
||||
- Auto-cleanup: retain only the 20 newest log files
|
||||
|
||||
### Headless Clients
|
||||
- Configure number of headless clients per server
|
||||
- Auto-launch when server starts, auto-kill when server stops
|
||||
- Connect to `127.0.0.1:[server_port]`
|
||||
|
||||
### Real-Time Updates
|
||||
- Socket.IO push for: server state, mission list, mod list, settings
|
||||
- All connected clients receive updates simultaneously
|
||||
|
||||
### Authentication
|
||||
- Optional HTTP Basic Auth (single or multiple users)
|
||||
- Credentials in `config.js`; no database
|
||||
|
||||
### Platform Support
|
||||
- Windows, Linux, Wine, Docker
|
||||
|
||||
---
|
||||
|
||||
## Data Persistence
|
||||
|
||||
| Data | Storage |
|
||||
|------|---------|
|
||||
| Server definitions | `servers.json` (plain JSON, in-memory on load) |
|
||||
| Mission files | `[game_path]/mpmissions/` (filesystem) |
|
||||
| Mod files | `[game_path]/[mod_dirs]/` (filesystem) |
|
||||
| Log files | Platform-specific log directory |
|
||||
| App config | `config.js` (static, not written at runtime) |
|
||||
|
||||
No database. All runtime state lives in the `Manager` class and is flushed to `servers.json` on every mutation.
|
||||
247
docs/CHERRY_PICK.md
Normal file
247
docs/CHERRY_PICK.md
Normal file
@@ -0,0 +1,247 @@
|
||||
# Cherry-Pick Candidates for languard-servers-manager
|
||||
|
||||
This document lists modules and functions from `arma-server-web-admin` that are worth adapting into `languard-servers-manager`. Each entry explains what the code does, why it is valuable, and a concrete adapter strategy.
|
||||
|
||||
Target project: `E:\TestScript\languard-servers-manager` (FastAPI + React stack).
|
||||
|
||||
---
|
||||
|
||||
## 1. Manager Pattern — Multi-Server Lifecycle Registry
|
||||
|
||||
**Source:** `lib/manager.js`
|
||||
**Key functions:** `load()`, `save()`, `addServer()`, `removeServer()`, `getServer()`, `getServers()`
|
||||
|
||||
**What it does:**
|
||||
Maintains an in-memory registry of Server instances (both as an ordered array and a hash for O(1) lookup), flushes state to `servers.json` on every mutation, and emits change events so the Socket.IO layer can broadcast diffs.
|
||||
|
||||
**Why it is valuable:**
|
||||
languard already has a similar concept (servers stored in SQLite), but the EventEmitter pattern that automatically triggers broadcasts on every mutation is clean and decoupled. The dual array+hash storage pattern is also worth copying for cache performance.
|
||||
|
||||
**Adapter strategy:**
|
||||
```
|
||||
Create: backend/core/servers/manager.py
|
||||
- ServerManager class with in-memory cache (dict + list)
|
||||
- on_change callback / asyncio.Event instead of EventEmitter
|
||||
- load() reads from SQLite via existing ServerRepository
|
||||
- save() writes back through repository
|
||||
- Emit WebSocket broadcasts via FastAPI WebSocket manager on every mutation
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Process Lifecycle — Start / Stop / Kill with Graceful Fallback
|
||||
|
||||
**Source:** `lib/server.js` — `start()`, `stop()` methods
|
||||
|
||||
**What it does:**
|
||||
Spawns a child process for the game server, captures its PID, starts a status-poll interval, pipes stdout/stderr to a log file, and on stop sends SIGTERM with a 5-second SIGKILL fallback. Headless clients are launched/killed alongside the main process.
|
||||
|
||||
**Why it is valuable:**
|
||||
languard's backend already launches processes, but the graceful stop with timed SIGKILL fallback and the headless client co-lifecycle are patterns not yet present.
|
||||
|
||||
**Adapter strategy:**
|
||||
```
|
||||
Adapt: backend/core/servers/process_manager.py
|
||||
- async def start_server(config) -> asyncio.subprocess.Process
|
||||
- async def stop_server(proc, timeout=5) -> SIGTERM then SIGKILL
|
||||
- Capture PID, store in DB server record
|
||||
- Pipe stdout/stderr to dated log file (matches existing log path logic)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Status Polling — Gamedig-style Periodic Query
|
||||
|
||||
**Source:** `lib/server.js` — `queryStatus()` + `setInterval` pattern
|
||||
|
||||
**What it does:**
|
||||
Every 5 seconds, queries the running game server via the game's UDP query protocol (Gamedig). Stores the response (`players`, `mission`, `state`) in the server's in-memory state and emits it to connected clients.
|
||||
|
||||
**Why it is valuable:**
|
||||
languard's frontend relies on WebSocket events pushed from process stdout. A periodic external query would give accurate player counts and current mission data independent of log output.
|
||||
|
||||
**Adapter strategy:**
|
||||
```
|
||||
Create: backend/core/servers/status_poller.py
|
||||
- asyncio.Task per running server (cancel on stop)
|
||||
- Use python-a2s or opengsq-python to query UDP game port
|
||||
- QueryAdapter interface: arma3, dayz, etc. as subclasses
|
||||
- On result: update server record in DB, push via WebSocket manager
|
||||
- Poll interval configurable (default 5 s)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Mod Discovery — Parallel Metadata Resolution
|
||||
|
||||
**Source:** `lib/mods/index.js`, `lib/mods/modFile.js`, `lib/mods/steamMeta.js`, `lib/mods/folderSize.js`
|
||||
|
||||
**What it does:**
|
||||
Finds all mod directories via glob, then for each mod concurrently: parses `mod.cpp` for display name, parses `meta.cpp` for Steam Workshop ID, and recursively calculates folder size with symlink-aware deduplication.
|
||||
|
||||
**Why it is valuable:**
|
||||
languard's mod tab lists paths but does not extract Steam IDs, human-readable names, or folder sizes. This pattern handles all three in parallel efficiently.
|
||||
|
||||
**Adapter strategy:**
|
||||
```
|
||||
Create: backend/core/mods/scanner.py
|
||||
- async def scan_mods(game_path: str) -> list[ModMeta]
|
||||
- Use pathlib.glob for discovery
|
||||
- asyncio.gather for parallel metadata:
|
||||
parse_mod_file(path) -> ModFileAdapter (reads mod.cpp)
|
||||
parse_steam_meta(path) -> SteamMetaAdapter (reads meta.cpp)
|
||||
folder_size(path) -> recursive os.scandir sum
|
||||
- ModMeta dataclass: { path, name, steam_id, size_bytes }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Log File Management — Platform Paths + Auto-Cleanup
|
||||
|
||||
**Source:** `lib/logs.js` — `logsPath()`, `logFiles()`, `cleanupOldLogFiles()`
|
||||
|
||||
**What it does:**
|
||||
Resolves the game log directory based on platform (windows / linux / wine). Lists `.rpt` files with metadata, auto-deletes the oldest files beyond a configurable retention limit (default 20).
|
||||
|
||||
**Why it is valuable:**
|
||||
languard streams real-time logs via WebSocket but has no endpoint to browse historical `.rpt` files on disk. Discovery and cleanup logic is directly reusable.
|
||||
|
||||
**Adapter strategy:**
|
||||
```
|
||||
Adapt: backend/core/logs/log_manager.py
|
||||
- def logs_path(platform: str, game_path: str) -> Path
|
||||
- def list_logs(logs_dir: Path) -> list[LogMeta] (stat each .rpt)
|
||||
- def cleanup_old_logs(logs_dir: Path, keep: int = 20)
|
||||
- Expose via:
|
||||
GET /api/servers/{id}/logfiles
|
||||
GET /api/servers/{id}/logfiles/{name}/download
|
||||
DELETE /api/servers/{id}/logfiles/{name}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Mission Multi-File Upload + Filename Parsing
|
||||
|
||||
**Source:** `lib/missions.js` — `updateMissions()` + `routes/missions.js` upload handler
|
||||
|
||||
**What it does:**
|
||||
Accepts multipart upload of up to 64 `.pbo` files simultaneously (parallel move with limit 8), scans the `mpmissions/` directory, and extracts `{ name, world }` from the Arma filename convention `missionname.worldname.pbo`.
|
||||
|
||||
**Why it is valuable:**
|
||||
languard's missions tab lists files but does not support drag-and-drop multi-file upload or Steam Workshop download. The `.pbo` filename parsing convention is Arma-specific and worth encoding explicitly.
|
||||
|
||||
**Adapter strategy:**
|
||||
```
|
||||
Adapt: backend/routers/missions.py
|
||||
- POST /api/servers/{id}/missions -> UploadFile[] via FastAPI
|
||||
- Validate .pbo extension server-side (reject others)
|
||||
- asyncio.gather with semaphore (limit 8): move to mpmissions/
|
||||
- Parse filename: "name.world.pbo" -> { name, world }
|
||||
- Trigger rescan -> return updated list
|
||||
- Optional: POST /api/missions/workshop { id } -> delegate to steamcmd
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. EventEmitter → WebSocket Broadcast Bridge
|
||||
|
||||
**Source:** `app.js` lines 49–66 (event bridge block)
|
||||
|
||||
**What it does:**
|
||||
Listens on EventEmitter events from Manager, Missions, and Mods, then calls `io.emit()` to broadcast to all connected Socket.IO clients. New connections receive a full state snapshot immediately on connect.
|
||||
|
||||
**Why it is valuable:**
|
||||
languard's WebSocket layer pushes real-time log lines but does not broadcast server state changes to all connected tabs/clients simultaneously. The "snapshot on connect + push diffs on change" pattern is directly applicable.
|
||||
|
||||
**Adapter strategy:**
|
||||
```
|
||||
Adapt: backend/core/websocket/broadcast_manager.py
|
||||
- WebSocketManager class (already partially exists in languard)
|
||||
- Add: publish(event: str, payload) -> broadcast_all()
|
||||
- On new connection: send snapshot of all servers, missions, mods
|
||||
- On server state change: publish("servers", get_all_servers())
|
||||
- Same for missions and mods events
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. Mission Rotation Table — Per-Mission Difficulty
|
||||
|
||||
**Source:** `public/js/app/views/servers/missions/rotation/` (list + item views)
|
||||
|
||||
**What it does:**
|
||||
Renders a table of missions in the server's active rotation. Each row has a difficulty dropdown. Rows can be added from the discovered mission list or removed individually. The full rotation array saves with the server config.
|
||||
|
||||
**Why it is valuable:**
|
||||
languard's missions tab shows available missions but has no drag-to-add rotation table with per-mission difficulty. This is a key Arma workflow.
|
||||
|
||||
**Adapter strategy:**
|
||||
```
|
||||
Adapt: frontend/src/pages/ServerDetailPage.tsx (Missions tab)
|
||||
- MissionRotationTable component
|
||||
- Row type: { name: string, difficulty: '' | 'Recruit' | 'Regular' | 'Veteran' }
|
||||
- Add row: select from available missions dropdown
|
||||
- Remove row: delete button per row
|
||||
- Save: PUT /api/servers/{id} { missions: [...] }
|
||||
- Backend: MissionRotationItem Pydantic schema as array field on Server
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. Mod Assignment UI — Split-Pane Available / Selected
|
||||
|
||||
**Source:** `public/js/app/views/servers/mods/` (available list + selected list views)
|
||||
|
||||
**What it does:**
|
||||
Two side-by-side lists: all discovered mods on the left, server-assigned mods on the right. Clicking a mod moves it between lists. Each list has a search filter. Selection saves when the settings form submits.
|
||||
|
||||
**Why it is valuable:**
|
||||
languard's mods tab uses a flat checkbox list. The split-pane pattern with instant visual feedback is significantly more usable when mod counts are large (50+).
|
||||
|
||||
**Adapter strategy:**
|
||||
```
|
||||
Adapt: frontend/src/pages/ServerDetailPage.tsx (Mods tab)
|
||||
- <AvailableModsList> and <SelectedModsList> side by side
|
||||
- Shared state: selectedMods: string[] (mod paths)
|
||||
- On click: immutable transfer between lists
|
||||
- Search input on each list (client-side filter)
|
||||
- On save: PUT /api/servers/{id} { mods: selectedMods }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 10. Startup Parameter Editor — Dynamic String List
|
||||
|
||||
**Source:** `public/js/app/views/servers/parameters/` (list + item views)
|
||||
|
||||
**What it does:**
|
||||
Renders a dynamic list of startup parameter inputs (e.g., `-limitFPS=100`). Rows can be added or removed. The list persists with the server config.
|
||||
|
||||
**Why it is valuable:**
|
||||
languard's Create Server wizard captures some fixed parameters but has no UI for arbitrary additional startup flags, which power users need.
|
||||
|
||||
**Adapter strategy:**
|
||||
```
|
||||
Create: frontend/src/components/ParameterEditor.tsx
|
||||
- Props: value: string[], onChange: (v: string[]) => void
|
||||
- Renders list of text inputs with remove buttons
|
||||
- Add button appends empty string
|
||||
- Used in: CreateServerPage wizard (step 3) and ServerDetailPage settings tab
|
||||
- Save: include in PUT /api/servers/{id} { parameters: [...] }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Priority Ranking
|
||||
|
||||
| Priority | Candidate | Effort | Value |
|
||||
|----------|-----------|--------|-------|
|
||||
| High | Status Polling (asyncio task per server) | Medium | Accurate live player counts |
|
||||
| High | Mission Rotation Table UI | Medium | Key missing workflow |
|
||||
| High | Mission Multi-File Upload | Low | Missing feature |
|
||||
| High | Mod Discovery with Parallel Metadata | Medium | Rich mod metadata |
|
||||
| Medium | Startup Parameter Editor UI | Low | Power-user feature |
|
||||
| Medium | Mod Split-Pane Selection UI | Medium | UX improvement for large mod lists |
|
||||
| Medium | Log File Discovery + Cleanup | Low | Historical log access |
|
||||
| Low | EventEmitter Broadcast Bridge | Low | Already partially implemented |
|
||||
| Low | Config-Driven Optional Auth | Low | Dev convenience only |
|
||||
314
docs/HOW_IT_WORKS.md
Normal file
314
docs/HOW_IT_WORKS.md
Normal file
@@ -0,0 +1,314 @@
|
||||
# How Arma Server Web Admin Works
|
||||
|
||||
## Application Boot Sequence
|
||||
|
||||
```
|
||||
node app.js
|
||||
├── Load config.js
|
||||
├── Create Express app + HTTP server
|
||||
├── Attach Socket.IO to HTTP server
|
||||
├── Instantiate: Settings, Missions, Mods, Manager
|
||||
├── Manager.load() → read servers.json, restore Server instances
|
||||
├── Register event bridges (manager/missions/mods → io.emit)
|
||||
├── Mount routes (/api/*)
|
||||
├── Serve public/ (SPA)
|
||||
├── Optional: setup-basic-auth middleware
|
||||
└── http.listen(config.port)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Core Flow: Server Lifecycle
|
||||
|
||||
### Start a Server
|
||||
|
||||
```
|
||||
POST /api/servers/:id/start
|
||||
→ routes/servers.js → manager.startServer(id)
|
||||
→ lib/server.js Server.start()
|
||||
├── Instantiate ArmaServer.Server with merged config
|
||||
├── Write server.cfg to filesystem (via arma-server lib)
|
||||
├── Spawn child process:
|
||||
│ Windows → arma3server.exe [params]
|
||||
│ Linux → ./arma3server [params]
|
||||
│ Wine → wine arma3server.exe [params]
|
||||
├── On Linux: pipe stdout/stderr to dated .rpt log file
|
||||
├── Start queryStatusInterval every 5 s (Gamedig)
|
||||
├── If number_of_headless_clients > 0 → startHeadlessClients()
|
||||
└── Emit 'state' event → manager bubbles → io.emit('servers', ...)
|
||||
```
|
||||
|
||||
### Stop a Server
|
||||
|
||||
```
|
||||
POST /api/servers/:id/stop
|
||||
→ Server.stop()
|
||||
├── instance.kill() (SIGTERM)
|
||||
├── setTimeout(5000) → instance.kill() if still alive (SIGKILL)
|
||||
├── stopHeadlessClients()
|
||||
├── clearInterval(queryStatusInterval)
|
||||
└── On 'close' → emit 'state'
|
||||
```
|
||||
|
||||
### Status Polling (every 5 seconds)
|
||||
|
||||
```
|
||||
setInterval → Server.queryStatus()
|
||||
→ Gamedig.query({ type: 'arma3', host: '127.0.0.1', port })
|
||||
→ On success: store { players, mission, status } in server.state
|
||||
→ On failure: set state = 'stopped' if instance.exitCode set
|
||||
→ Emit 'state' → manager → io.emit('servers', getServers())
|
||||
```
|
||||
|
||||
### Persistence
|
||||
|
||||
```
|
||||
Any mutation (add/edit/delete/start/stop)
|
||||
→ Manager.save()
|
||||
→ JSON.stringify(serversArr.map(s => s.toJSON()))
|
||||
→ Write to servers.json
|
||||
→ Emit 'servers' event → io.emit('servers', ...)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Core Flow: Mission Management
|
||||
|
||||
### List Missions
|
||||
|
||||
```
|
||||
GET /api/missions/
|
||||
→ missions.missions (pre-loaded array)
|
||||
→ [ { name, world, filename, size, created, modified }, ... ]
|
||||
```
|
||||
|
||||
### Upload Missions
|
||||
|
||||
```
|
||||
POST /api/missions (multipart/form-data, field: "missions")
|
||||
→ multer stores files to temp dir
|
||||
→ Filter: only .pbo extension allowed
|
||||
→ async.parallelLimit(8): fs.move(temp → mpmissions/filename)
|
||||
→ missions.updateMissions()
|
||||
→ fs.readdir(mpmissions/)
|
||||
→ stat each file → build metadata object
|
||||
→ update this.missions array
|
||||
→ io.emit('missions', missions.missions)
|
||||
```
|
||||
|
||||
### Steam Workshop Download
|
||||
|
||||
```
|
||||
POST /api/missions/workshop { id: "workshop_id" }
|
||||
→ steamWorkshop.downloadFile(id, mpmissionsDir)
|
||||
→ missions.updateMissions()
|
||||
→ io.emit('missions', ...)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Core Flow: Mod Management
|
||||
|
||||
### Discovery Pipeline
|
||||
|
||||
```
|
||||
Mods.updateMods()
|
||||
→ glob('**/{@*,csla,ef,...}/addons', gamePath)
|
||||
→ For each modDir, async.map → resolveModData(modDir)
|
||||
├── async.parallel:
|
||||
│ folderSize(modDir) → recursive sum of file sizes (symlink-aware)
|
||||
│ modFile(modDir) → parse mod.cpp → { name }
|
||||
│ steamMeta(modDir) → parse meta.cpp → { id, name }
|
||||
└── Merge results into:
|
||||
{ name: relative_path, size, formattedSize, modFile, steamMeta }
|
||||
→ this.mods = result array
|
||||
→ Emit 'mods'
|
||||
```
|
||||
|
||||
### Assign Mods to Server
|
||||
|
||||
```
|
||||
Client UI: drag/click mod from "Available" → "Selected"
|
||||
→ Backbone model update: server.mods = [ 'path/to/@mod', ... ]
|
||||
→ PUT /api/servers/:id { mods: [...] }
|
||||
→ manager.saveServer(id, body)
|
||||
→ Manager.save() → servers.json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Core Flow: Log Management
|
||||
|
||||
### Locate Log Files
|
||||
|
||||
```
|
||||
Logs.logsPath()
|
||||
→ if config.type === 'windows' → AppData/Local/[GameName]/
|
||||
→ if config.type === 'linux' → config.path/logs/
|
||||
→ if config.type === 'wine' → .wine/drive_c/users/.../AppData/[GameName]/
|
||||
|
||||
Logs.logFiles()
|
||||
→ fs.readdir(logsPath)
|
||||
→ filter: /\.rpt$/
|
||||
→ stat each → { name, size, created, modified }
|
||||
→ sort by modified desc
|
||||
```
|
||||
|
||||
### Auto-Cleanup
|
||||
|
||||
```
|
||||
After any delete or Linux log write:
|
||||
Logs.cleanupOldLogFiles()
|
||||
→ logFiles() → sort by modified
|
||||
→ if count > 20: delete oldest (count - 20) files
|
||||
```
|
||||
|
||||
### Linux Real-Time Logging
|
||||
|
||||
```
|
||||
Server.start() (Linux)
|
||||
→ logStream = fs.createWriteStream(logPath, { flags: 'a' })
|
||||
→ process.stdout.pipe(logStream)
|
||||
→ process.stderr.pipe(logStream)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Real-Time Architecture (Socket.IO)
|
||||
|
||||
```
|
||||
Backend (EventEmitter chain)
|
||||
Manager/Missions/Mods emit events via Node EventEmitter
|
||||
app.js bridges each to Socket.IO:
|
||||
manager.on('servers', () => io.emit('servers', manager.getServers()))
|
||||
missions.on('missions', (m) => io.emit('missions', m))
|
||||
mods.on('mods', (m) => io.emit('mods', m))
|
||||
|
||||
On new client connection:
|
||||
socket.emit('missions', missions.missions) // push initial snapshot
|
||||
socket.emit('mods', mods.mods)
|
||||
socket.emit('servers', manager.getServers())
|
||||
socket.emit('settings', settings.getPublicSettings())
|
||||
|
||||
Frontend (Backbone + Socket.IO)
|
||||
socket.on('servers', (servers) → serversCollection.set(servers))
|
||||
socket.on('missions', (m) → missionsCollection.set(m))
|
||||
socket.on('mods', (m) → modsCollection.set(m))
|
||||
→ Backbone triggers 'change'/'add'/'remove' → Marionette re-renders views
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Frontend SPA Architecture
|
||||
|
||||
### Routing
|
||||
|
||||
Five Backbone routes drive the entire SPA:
|
||||
|
||||
| Route | Handler | View |
|
||||
|-------|---------|------|
|
||||
| `` (home) | `home()` | `ServersListView` — server grid |
|
||||
| `logs` | `logs()` | `LogsListView` — log file browser |
|
||||
| `missions` | `missions()` | `MissionsView` — upload + list |
|
||||
| `mods` | `mods()` | `ModsView` — mod browser |
|
||||
| `servers/:id` | `server(id)` | `ServerView` — tabbed detail page |
|
||||
|
||||
### View Hierarchy
|
||||
|
||||
```
|
||||
LayoutView (root, persists across route changes)
|
||||
├── Region: navigation → NavigationView (server list sidebar)
|
||||
└── Region: content → (swapped per route)
|
||||
├── ServersListView
|
||||
│ └── ServerItemView (per server card)
|
||||
├── LogsListView
|
||||
│ └── LogItemView (per log file)
|
||||
├── MissionsView
|
||||
│ ├── UploadView (file input + drag-and-drop)
|
||||
│ ├── WorkshopView (Steam ID input)
|
||||
│ └── MissionsListView → MissionItemView
|
||||
├── ModsView
|
||||
│ ├── AvailableModsListView → ModItemView
|
||||
│ └── SelectedModsListView → SelectedModItemView
|
||||
└── ServerView (tabbed LayoutView)
|
||||
├── Tab: Info → InfoView (status, start/stop, PID, players)
|
||||
├── Tab: Mods → ServerModsView (split pane)
|
||||
├── Tab: Missions → MissionRotationView (add/remove rotation rows)
|
||||
├── Tab: Parameters → ParametersView (startup param editor)
|
||||
├── Tab: Players → PlayersView (live player table)
|
||||
└── Tab: Settings → FormView (full server config form)
|
||||
```
|
||||
|
||||
### Settings Form Save Flow
|
||||
|
||||
```
|
||||
FormView.save()
|
||||
→ Collect: jQuery serializeArray() + checkbox state
|
||||
→ Validate: title required
|
||||
→ AJAX PUT /api/servers/:id { ...formData }
|
||||
→ On 200: server model updated, navigate to /servers/:newId
|
||||
→ On error: SweetAlert error dialog
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Configuration System
|
||||
|
||||
### Global Config (`config.js`)
|
||||
|
||||
```javascript
|
||||
{
|
||||
game: 'arma3', // Game variant
|
||||
path: '/opt/arma3', // Game install path
|
||||
port: 3000, // Web UI port
|
||||
host: '0.0.0.0',
|
||||
type: 'linux', // 'windows' | 'linux' | 'wine'
|
||||
parameters: [], // Global startup params (all servers)
|
||||
serverMods: [], // Server-side mods (all servers)
|
||||
admins: [], // Steam IDs auto-granted admin
|
||||
auth: { username, password }, // Optional Basic Auth
|
||||
prefix: '', // Prepended to all server hostnames
|
||||
suffix: '',
|
||||
additionalConfigurationOptions: '' // Appended to all server.cfg
|
||||
}
|
||||
```
|
||||
|
||||
### Per-Server Config (stored in `servers.json`)
|
||||
|
||||
```javascript
|
||||
{
|
||||
id: 'my-server', // URL-safe slug of title
|
||||
title: 'My Server',
|
||||
port: 2302,
|
||||
max_players: 32,
|
||||
password: '',
|
||||
admin_password: '',
|
||||
motd: '',
|
||||
auto_start: false,
|
||||
battle_eye: true,
|
||||
persistent: false,
|
||||
von: true,
|
||||
verify_signatures: false,
|
||||
file_patching: false,
|
||||
allowed_file_patching: 0,
|
||||
forcedDifficulty: '',
|
||||
number_of_headless_clients: 0,
|
||||
parameters: [],
|
||||
additionalConfigurationOptions: '',
|
||||
missions: [{ name: 'mission.world', difficulty: '' }],
|
||||
mods: ['@CBA_A3', '@ACE']
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Authentication Flow
|
||||
|
||||
```
|
||||
If config.auth defined:
|
||||
setupBasicAuth(app, config.auth)
|
||||
→ app.use(expressBasicAuth({ users: { username: password } }))
|
||||
→ All routes require valid Authorization: Basic ... header
|
||||
→ req.auth.user available in all route handlers
|
||||
→ Morgan logs include authenticated username
|
||||
```
|
||||
Reference in New Issue
Block a user