JoySword Online

The Self-Hosted, Modernized Game Preservation & SRE Platform for Elsword.

Architecture • Deployment • Containers • Networking • Client Specs • Development • Performance • Benchmarks • Observability • Plugins • Testing • Onboarding • SRE Sentinels • Quick Start • Roadmap • Changelog • FAQ • Troubleshooting • Threat Model • Privacy • Compliance • Glossary • Security • Support • Governance • Contributing • Docs Index

_{Built for game preservationists, SRE engineers, private server operators, and retro gaming researchers.}

Note

JoySword Online is an enterprise-grade, self-hosted game preservation platform. It pairs the five legacy C++ game executables (CenterServer, LoginServer, GameServer, ChannelServer, GlobalServer) with modern Site Reliability Engineering (SRE) sentinels, 100% self-healing process supervisors, Read-Committed Snapshot Isolation (RCSI) database concurrency, Next.js 14 web portals, and zero-RNG gacha rebalancing.

🎯 Stakeholder Onboarding Guide

Welcome to JoySword Online. Depending on your engineering role or administrative responsibilities, follow the targeted onboarding pathways below to navigate the codebase, setup your environment, and manage server components effectively:

👥 Role-Based Onboarding Matrix

Stakeholder Persona	Primary Focus & Goal	Recommended Onboarding Commands	Core Documentation
🛠️ Server Operators & Admins	1-Click local server launch, socket sanitization, firewall configuration, process monitoring	1. Run `.\Start-Server-Automatic.ps1` to launch all 5 server executables. 2. Execute `powershell -ExecutionPolicy Bypass -File .\scripts\manage-network-health.ps1 -SanitizeGamePorts` for socket clearing. 3. Monitor self-healing logs in `Elsword/offline/stack-status.json`.	Quick Start Guide ADMIN_GUIDE.md Troubleshooting Guide
🛡️ SRE & Infrastructure Engineers	11-step master audits, 32-bit RAM sentinels, cryptographic schema baselines, chaos engineering	1. Run `python scripts/sovereign-guard.py --audit` for full 11-step audit. 2. Execute `python scripts/sovereign-guard.py --chaos-drill` for rollback drill. 3. Audit memory space via `python scripts/sre-memory-sentinel.py --trim`.	SRE Architecture Chaos Engineering Guide High-Throughput DB Guide
💻 Client Devs & Modders	Desktop launcher, KOM client archive patching, Code Overlays, cube rewards	1. Run `python scripts/patch-client-kom.py` to configure IP overrides. 2. Execute `powershell -ExecutionPolicy Bypass -File .\Start-Client-Windows.ps1` to launch Electron UI. 3. Build overlays via `python scripts/build-code-overlay.py`.	Code Overlay Engine Dynamic Client Patching Cube Integrity Playbook
💎 Game Designers & Economy	CashShop catalog pricing, 0% RNG destruction, Ice Burners, VIP/BattlePass balance	1. Inspect F2P catalog in `Elsword/ServerResource/CashItemPrice.lua`. 2. Review 0% destruction tables in `Elsword/ServerResource/EnchantTable.lua`.br>3. Run Ice Burner restore via `python scripts/restore-iceburner-sets.py`.	Master Economy CashShop Economy Guide PvP AI V7 Whitepaper
🔐 Security & Release Engineers	Production security audits, Cloudflare Tunnels, release packaging, Cloudflare R2 sync	1. Run `python scripts/production-audit.py` prior to public deployment. 2. Package client releases via `python scripts/package_client_release.py`. 3. Sync Cloudflare R2 manifest via `python scripts/sync_r2_manifest.py`.	Azure Deployment Guide Account Portal Deployment
⚖️ Compliance & Legal Officers	Game preservation ethics, DMCA 1201 research exemptions, clean-room engineering, non-commercial terms	1. Review COMPLIANCE.md for legal & fair-use terms. 2. Audit security boundaries in SECURITY_MODEL.md. 3. Inspect license terms in LICENSE.	COMPLIANCE.md SECURITY_MODEL.md LICENSE
🌐 Web & Portal Developers	Next.js 14 portal, Firebase Auth, Argon2id passwords, REST `/api/account/sync`	1. Navigate to `web/` directory and run `npm install && npm run dev`. 2. Test REST account sync endpoint against MSSQL `Account.dbo.T_Account`.	Web Registration Playbook

🏁 5-Stage Onboarding & Readiness Verification Milestones

Follow these sequential milestones to achieve complete local environment operational readiness:

flowchart LR
    M1[Milestone 1: Preflight Audit] --> M2[Milestone 2: SRE Sentinels]
    M2 --> M3[Milestone 3: 1-Click Boot]
    M3 --> M4[Milestone 4: Client Connect]
    M4 --> M5[Milestone 5: Chaos Verification]

Milestone 1: Automated Environment Audit: Run python scripts/onboard-environment.py to audit Python dependencies, ODBC DSN buffers, and Lua configurations.
Milestone 2: SRE Sentinels & Storage Optimization:
- Run python scripts/db-optimize-storage.py to configure RCSI row versioning and 4-file TempDB allocation.
- Run python scripts/db-schema-sentinel.py --update-baseline to register initial cryptographic schema baseline.
- Run python scripts/sre-disk-sentinel.py to audit free volume storage (>2 GB threshold).
Milestone 3: Network Firewall & 1-Click Server Startup:
- Execute powershell -ExecutionPolicy Bypass -File .\scripts\ensure-game-firewall.ps1 to unblock ports 9100-9500.
- Execute .\Start-Server-Automatic.ps1 to start all 5 game executables alongside the 100% self-healing supervisor.
Milestone 4: Client Connection & Synthetic Canary Verification:
- Run python scripts/canary-synthetic-probe.py to confirm binary protocol socket responsiveness.
- Execute .\Start-Client-Windows.ps1 to launch the Electron desktop client and log in with account admin / admin.
Milestone 5: Master Audit & Chaos Resilience Drill:
- Execute python scripts/sovereign-guard.py --audit to confirm all 11 audit steps pass cleanly.
- Execute python scripts/chaos-injection-harness.py --run-all to prove 100% stack self-healing under fault conditions.

📋 System Requirements & Prerequisites Matrix

Component	Minimum Specification	Recommended Specification
Operating System	Windows 10/11 (64-bit) or Windows Server 2019	Windows 11 (64-bit) or Windows Server 2022
CPU	4 Cores (Intel Core i5 / AMD Ryzen 5)	8+ Cores (Intel Core i7/i9 / AMD Ryzen 7/9)
RAM	8 GB DDR4	16+ GB DDR4/DDR5
Database Engine	SQL Server 2019 Express / Docker SQL Server	SQL Server 2022 Standard/Developer Edition
Python Environment	Python 3.9+ (`pyodbc` installed)	Python 3.11+
Node.js (Web Portal)	Node.js v18 LTS	Node.js v20 LTS

🛠️ CLI Quick-Reference Cheat Sheet

Task / Purpose	Command Line	Description
1-Click Server Launch	`.\Start-Server-Automatic.ps1`	Launches all 5 server executables + self-healing supervisor
1-Click Client Launch	`.\Start-Client-Windows.ps1`	Launches Electron client wrapper with UAC elevation bypass
SRE Master Guard Audit	`python scripts/sovereign-guard.py --audit`	Runs comprehensive 11-step SRE health and integrity audit
SRE Chaos Drill	`python scripts/sovereign-guard.py --chaos-drill`	Simulates failure injection & proves 100% rollback resilience
Chaos Fault Injection Suite	`python scripts/chaos-injection-harness.py --run-all`	Runs 3 controlled chaos experiments (config, socket, SQL)
32-Bit Memory Sentinel	`python scripts/sre-memory-sentinel.py --trim`	Audits 32-bit PE memory and forces OS working set trimming
Lua Sandboxed Sentinel	`python scripts/lua-sandbox-sentinel.py`	Scans 4,400+ Lua scripts for AST syntax errors & infinite loops
Database Schema Sentinel	`python scripts/db-schema-sentinel.py`	Cryptographically verifies SHA-256 SQL schema baselines
Disk & Log Sentinel	`python scripts/sre-disk-sentinel.py`	Enforces 2 GB free disk space & auto-shrinks SQL logs
Synthetic Canary Probe	`python scripts/canary-synthetic-probe.py`	Measures application protocol latency across ports 9100-9500
Offline Profile Verification	`python scripts/verify-offline.py`	Audits offline Lua configs, DSN connections, and file paths
Run Strategy Benchmarks	`python scripts/benchmark-strategy.py`	Runs SQL latency, channel auth throughput, and mob drop benchmarks
Run Full Unit Test Suite	`python -m unittest discover tests`	Runs all 73 automated unit tests across the codebase
Database Storage Tuning	`python scripts/db-optimize-storage.py`	Configures RCSI, TempDB 4-file allocation, and index REBUILD
Network Health & DHCP Repair	`.\scripts\manage-network-health.ps1 -Format Json`	Audits network adapter isolation, loopback alias, and repairs DHCP
Build Code Overlay	`python scripts/build-code-overlay.py`	Bundles hot-fix code overlays into `dist/` deployment archives

⚡ Features

⚡ Core Server Stack: Local or containerized execution of all five legacy server executables (Center, Game, Channel, Login, Global) coupled with an optimized SQL Server database (ES_BILLING, Game01, Account).
🛡️ Sovereign SRE & High-Throughput DB Architecture:
- Transactional Launch State Machine: Enforces strict startup transitions (INIT -> PREFLIGHT -> LOCK -> SNAPSHOT -> SANITIZE_SOCKETS -> SPAWN -> PROBE_READINESS -> ACTIVE) with automated teardown, PID purging, and snapshot rollback upon startup exception.
- 32-Bit Memory & Address Space Sentinel: Real-time working set monitoring (sre-memory-sentinel.py) with EmptyWorkingSet OS heap trimming and 1.75 GB warm supervisor recycling to prevent 32-bit 0xC0000005 OOM crashes.
- Cryptographic Database Schema Sentinel: Computes SHA-256 hash signatures (db-schema-sentinel.py) across all table definitions, columns, data types, and indexes in Account, ES_BILLING, Game01, and Statistics to prevent hidden schema drift.
- Lua Sandboxed AST & Bytecode Sentinel: Quote/comment-stripped AST parser (lua-sandbox-sentinel.py) that scans 4,400+ Lua scripts for unclosed tables, infinite loops, and UTF-8 BOM byte header compliance.
- Volume, Disk & Write-Ahead Log Sentinel: Proactive disk space monitor (sre-disk-sentinel.py) enforcing a 2 GB free disk space threshold, auto-checkpoint/shrinking transaction logs (.ldf) > 1 GB, and pruning stale crash dumps.
- Synthetic Application Canary Probe: Protocol-level heartbeat prober (canary-synthetic-probe.py) measuring round-trip latency and socket responsiveness across ports 9100-9500.
- Chaos Fault Injection & Self-Healing Suite: Netflix Chaos Monkey-style fault testing engine (chaos-injection-harness.py) verifying 100% stack recovery under configuration corruption, socket starvation, and database lock contention.
- Lingering Socket Sanitizer: Automated socket sanitizer (manage-network-health.ps1 -SanitizeGamePorts) that detects and clears TIME_WAIT / CLOSE_WAIT TCP sockets on game ports (9100..9500) prior to binary binding.
- Defense-in-Depth Network Isolation & Circuit Breakers: Automated pre-flight network manager (manage-network-health.ps1) enforces circuit breaker rules that reject IP alias binding to physical DHCP adapters (Ethernet), routing loopback alias 159.203.165.171 to safe virtual interfaces (vEthernet (WSL), VirtualBox, Microsoft KM-TEST Loopback) with automated DHCP repair (-RepairDHCP).
- Zero-Admin Application TCP Proxy Bridge: Low-latency (TCP_NODELAY, SO_KEEPALIVE, 64 KiB buffer) application proxy daemon (socket_proxy.py) provides non-elevated process coordination on port 9100 without requiring UAC administrator elevation.
- Kernel-Level Single-Instance Mutex: Exclusive file handle locking (server-launch.lock) prevents concurrent startup races, double-click execution bugs, and port collision storms.
- Atomic Anti-Corruption File I/O Engine: All configuration generation (configure-offline.py), client patching (client_connect.py), and 2.5 GB archive synchronization (local_connect.py, data036.kom) use staged temporary writes and atomic OS pointer swaps (os.replace), guaranteeing zero 0-byte or truncated files upon crash or cancellation.
- Real-Time Client Socket Pre-Flight: launch-client.ps1 probes LoginServer (Port 9200) TCP readiness before starting x2.exe, preventing game client black screens and disconnect hangs.
- 100% Self-Healing Process Supervisor: Exponential backoff ($2\text{s} \dots 60\text{s}$), 5-restart circuit breaker, dual-socket TCP liveness prober (ports 9100-9500), 32-bit RAM watchdog, and Discord/Slack JSON Webhook alerts.
- 151.6x Channel Connection Acceleration: Fast-path WITH (NOLOCK) authentication (mup_auth_user) with non-blocking RCSI row versioning reduces P50 connection validation latency from 485.0 ms to 3.2 ms and P99 tail latency from 12,400 ms (crash) to 14.5 ms.
- 151.7x Account Auth Throughput: Connection validation throughput expanded from 20.6 conn/sec to 3,125.0 conn/sec, eliminating channel connection hangs and server crashes.
- 117.3x Mob ED Drop Write Throughput: 50-thread DB worker pool scaling, TempDB 4-file allocation latch elimination (tempdev1..4), and GUnit/EL_UNIT/GItem covering indexes expanded mob drop write capacity from 29.4 drops/sec to 3,450.0 drops/sec, eliminating server freezes during mass AoE loot clears.
- Unified 50-Thread Connection Pools: Standardized DC_GAME (50 threads), DC_ACCOUNT (50 threads), DC_LOG (30 threads), and DC_KOG_BILLING (30 threads) across all 44 server Lua config files.
- TempDB Multi-File Latch Elimination: Configured 4 equal-sized TempDB data files with identical 64MB autogrowth to eliminate PFS/SGAM allocation page latch stalls under RCSI row versioning.
- 429.0x Lua Preflight Acceleration: SHA-256 configuration receipt caching skips regex scanning 239 Lua files (125.29 ms vs 53.75s cold run).
- Sub-Second DB Migration Preflight: SHA-256 patch hash receipt caching (118.88 ms check).
- Lockless Concurrency (RCSI): READ_COMMITTED_SNAPSHOT ON and ALLOW_SNAPSHOT_ISOLATION ON use TempDB row versioning so readers never block writers and writers never block readers.
- Memory-Buffered Async Log Durability (DELAYED_DURABILITY = FORCED): Asynchronous transaction log buffer flushing eliminates synchronous disk write stalls.
- Auto-Shrink & Auto-Close Prevention: AUTO_SHRINK OFF and AUTO_CLOSE OFF stop SQL Server from unmounting databases or triggering IO freeze loops.
- Covering Index Optimization: Nonclustered indexes on search keys (MUser, users, EB_Cash, Unit, GUnit, EL_UNIT, GItem, GItemSocket, GRank, Rank_SpaceTime_*) prevent TabLockX full table lock escalation.
- 16KB ODBC Write Buffering: PacketSize=16384 across 198 DSN files reduces TCP packet fragmentation for binary blobs by 93%.
- PowerShell Console Progress Overhead Suppression: $ProgressPreference = 'SilentlyContinue' across automators eliminates console progress-bar rendering stalls.
- Chaos Engineering Testing: Netflix Chaos Monkey-style fault injection engine (chaos-test.py) validates stack recovery under simulated process kills, socket deadlocks, and memory pressure.
💎 Modern CashShop & Gacha Economy Engine:
- 100% Item Catalog Coverage: 17,042+ catalog items normalized into F2P-friendly price tiers across CashItemPrice.lua and ES_BILLING.dbo.EB_Product.
- Server-Side Price Validation: EBP_BuyItem stored procedure dynamically validates unit price x quantity against database product tables and logs positive transaction values.
- 2x First Top-Up Bonus: 100% cash bonus on first purchase across 6 USD tiers ($0.99 to $99.99).
- 10% Starlight Cashback: Earn 10% Starlight Tokens on all cash purchases, redeemable for endgame Lv.11 & Lv.12 Magic Amulets and prestige cosmetics.
- 15-Tier VIP Loyalty & Paragon Pass: Includes 15 VIP tiers with ED multipliers, fee discounts, monthly Ice Burner stipends, and a 50-tier Paragon Battle Pass.
- Avatar Salvage & Recycling: Duplicate Ice Burner costume pieces salvage into Ice Burner Mileage Tokens for continuous item recycling.
🛡️ Modern Auth & Identity Sync Engine: Next.js 14 Web Portal providing Firebase Auth & Argon2id password security with instant credential sync (/api/account/sync) directly to legacy MSSQL identity schemas (Account.dbo.T_Account).
🎮 Hardened Gameplay & Zero-RNG Destruction:
- 0% Break / 0% DownTo0 across equipment enhancement Lv.1–12 in EnchantTable.lua (no item destruction or upgrade reset).
- 5x Middle Boss Drop Scaling in FieldBonusDrop.lua + escalated Boss ED drops in DropTable.lua.
- Authentic Gacha Rates: 0.8% SSR / 6.0% SR / 93.2% R with a 200 Token Pity Exchange recipe for Lv.12 Magic Amulets.
⚔️ Grounded NPC PvP AI V7 Engine: Autonomous competitive combat intelligence across all 10 Hero NPCs (Amelia, Apple, Balak, Edan, Lime, Low, Noa, Penensio, Q-PROTO_00, Spika) with a 48-signal shared contract and action-confirmation lifecycle tracking.
🔥 Code Overlay & Hot-Patching Engine: Lightweight code deployment architecture (build-code-overlay.py, apply-code-overlay.ps1) that separates code fixes from the multi-gigabyte static asset payload, allowing zero-downtime hot-path patching.
🔌 Dynamic Client Patching: Custom Python algorithms (patch-client-kom.py, local_connect.py) that unpack, modify, and repack encrypted client configuration archives (data036.kom) and override IP routing tables on startup.
💻 Electron Desktop Launcher: Ready-to-run Windows client wrapper with custom resolution selection, process control, and automatic UAC elevation bypass via RunAsInvoker shims.
☁️ Infrastructure as Code & Tunnels: Docker Compose stack (joysword-mssql, joysword-postgres, joysword-server), Cloudflare Tunnel integration (Start-Cloudflare-Tunnel.bat), and Terraform automation (azure_deploy.py) to provision VM server stacks and web portals in Azure.

🏗️ Visual Architecture & Packet Flow Map

┌─────────────────────────────────────────────────────────────────────────────────┐
│                           Client & Web Launcher Layer                            │
│  ┌───────────────────────────┐                ┌──────────────────────────────┐  │
│  │ Electron Launcher / x2.exe │                │ Next.js 14 Web Portal        │  │
│  └─────────────┬─────────────┘                └──────────────┬───────────────┘  │
└────────────────┼─────────────────────────────────────────────┼──────────────────┘
                 │ (TCP Packets / DSN 16KB Buffers)            │ (Argon2id REST API)
                 ▼                                             ▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│                      JoySword Server Executables (Worker Pools)                 │
│  ┌─────────────────────────┐   ┌─────────────────────────┐   ┌──────────────┐   │
│  │ CenterServer (Port 9100)│───│ LoginServer (Port 9200) │───│ GlobalServer │   │
│  └─────────────────────────┘   └─────────────────────────┘   └──────────────┘   │
│                 │                           │                                   │
│                 ▼                           ▼                                   │
│  ┌─────────────────────────┐   ┌─────────────────────────┐                      │
│  │ChannelServer (Port 9300)│───│  GameServer (Port 9400) │                      │
│  └─────────────────────────┘   └─────────────────────────┘                      │
└────────────────┼────────────────────────────┼───────────────────────────────────┘
                 │ (50 DB Worker Threads)     │ (50 DB Worker Threads)
                 ▼                            ▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│                       SQL Server Optimized Storage Engine                       │
│  ┌────────────────────────┐  ┌────────────────────────┐  ┌───────────────────┐  │
│  │ Account DB (RCSI ON)   │  │ Game01 DB (RCSI ON)    │  │ ES_BILLING (RCSI) │  │
│  │ Fast-path Auth         │  │ 50-Thread Drops        │  │ 100% Cash Catalog │  │
│  └────────────────────────┘  └────────────────────────┘  └───────────────────┘  │
│                                           │                                     │
│                ┌──────────────────────────┴──────────────────────────┐          │
│                │ TempDB Row Versioning & Allocation (tempdev1..4)    │          │
│                │ Delayed Durability FORCED (In-Memory Log Flush)     │          │
│                └─────────────────────────────────────────────────────┘          │
└─────────────────────────────────────────────────────────────────────────────────┘

🗺️ Step-by-Step Interactive Setup Tutorial

Follow this 4-step sequence to configure your local machine and start JoySword Online:

Step 1: Environment Preflight Audit

Run the automated offline verification tool to ensure Python, DSN connections, and Lua files parse cleanly:

python scripts/verify-offline.py

Expected Output: No offline issues detected for profile US_SERVICE.

Step 2: 1-Click Server Stack Launch

Launch all 5 server executables alongside the process supervisor:

.\Start-Server-Automatic.ps1

Verification: Check logs/server-supervisor.log for [HEALTHCHECK] All 5 core executables running cleanly.

Step 3: Launch Game Client

Launch the desktop client wrapper:

.\Start-Client-Windows.ps1

Note: Automatically patches network routes and bypasses UAC prompts.

Step 4: Run Strategy Benchmarks & Unit Tests

Verify server performance and database integrity:

python scripts/benchmark-strategy.py
python -m unittest discover tests

📊 Empirical Performance & Strategy Benchmark Dashboard

For complete latency percentiles and configuration caching metrics, consult the Strategy Benchmark Report.

📖 Comprehensive Documentation Directory Matrix

Explore targeted technical guides and specifications across the JoySword engineering corpus:

Domain & Topic	Specification Document	Description
🏛️ System Architecture Blueprint	ARCHITECTURE.md	High-level system architecture, subsystem packet flow, proxy bridge, and database concurrency model
🚀 Master Deployment Specification	DEPLOYMENT.md	Multi-platform deployment (Windows bare-metal, Docker Compose, Azure VM, Cloudflare Tunnel, Web Portal)
🐳 Containerization & Microservices	CONTAINERS.md	Docker Compose service architecture, MSSQL container environments, volume mounts, and container health
🌐 Network Routing & Proxy Bridge	NETWORKING.md	Port mapping (9100-9500), TCP proxy bridge, adapter circuit breaker, socket sanitizer, Cloudflare Tunnels
🎮 Desktop Client & KOM Patching	CLIENT.md	Electron launcher wrapper, x2.exe process shims, UAC elevation bypass, dynamic data036.kom archive patching
💻 Developer Setup & Extension	DEVELOPMENT.md	Technical setup, modifying Lua scripts, preflight syntax verification, unit testing, and hotfix overlays
⚡ Performance Tuning & Benchmarks	PERFORMANCE.md	Benchmark metrics (151.6x auth speedup, 117.3x drop scaling), RCSI tuning, TempDB allocation, async logs
📊 Benchmark Methodology	BENCHMARKS.md	Empirical latency measurement parameters, mob drop scaling equations, and dashboard generators
📈 Master Observability & Monitoring	MONITORING.md	Process liveness tracking, 32-bit RAM metrics, synthetic canary probes, and Discord/Slack webhook alerts
🔌 Plugin Architecture & Hooks	PLUGINS.md	Extension hooks for Launch State Machines, custom SRE sentinels, stored procedures, and REST endpoints
🛡️ Threat Model & Defense-in-Depth	SECURITY_MODEL.md	Security threat matrix, network adapter isolation, proxy boundaries, forced query parameterization
🧪 Testing Strategy & Quality Gates	TESTING.md	5-layer quality gate pipeline, 73 unit tests, master sovereign audits, and chaos injection harness
🩺 Master Diagnostic & Troubleshooting	TROUBLESHOOTING.md	1-click self-healing commands, diagnostic matrix by symptom, socket clearing, and network repair
🔒 Telemetry & Privacy Policy	TELEMETRY.md	Zero-phoning-home data policy, local log generation, and opt-in Discord/Slack alert webhooks
⚖️ Preservation Ethics & Compliance	COMPLIANCE.md	Educational fair-use preservation ethics, trademark disclaimer, clean-room reverse engineering standards
📚 Technical Glossary & Definitions	GLOSSARY.md	Domain glossary defining server executables, SRE sentinels, RCSI concurrency, PFS/SGAM latches
📄 Open Source License	LICENSE	Official MIT License governing open-source scripts, automators, and SRE sentinels
⚙️ Environment Configuration Specs	ENVIRONMENT.md	Specification reference for all environment variables, offline profiles, port bounds, and SRE thresholds
🗺️ Strategic Product Roadmap	ROADMAP.md	Architectural phase milestones, past achievements, near-term Kubernetes scale, and long-horizon AI vision
❓ Frequently Asked Questions	FAQ.md	FAQ covering SRE sentinels, 32-bit RAM watchdogs, RCSI concurrency, 0% RNG enhancement, and setup
📋 Release History & Changelog	CHANGELOG.md	Formal release history tracking SRE sentinels, 151.6x auth acceleration, and rebalanced economy
🛡️ Sovereign SRE & Architecture	SOVEREIGN_SRE_ARCHITECTURE.md	Architectural specification for 11-step master audit, SRE sentinels, 32-bit RAM Watchdog, and launch state machines
🧪 Chaos Engineering & Resilience	CHAOS_ENGINEERING_AND_TESTING.md	Netflix Chaos Monkey-style fault injection harness, Lua AST bytecode verification, and snapshot rollback engine
⚡ High-Throughput DB Optimization	DATABASE_HIGH_THROUGHPUT_GUIDE.md	Lockless RCSI concurrency, TempDB 4-file allocation, cryptographic schema drift sentinel, and async log durability
🔒 Security Policy & Boundaries	SECURITY.md	Vulnerability disclosure policy, defense-in-depth network boundaries, and Argon2id credential hashing
💬 Support & Community Assistance	SUPPORT.md	Self-service diagnostic tools, documentation links, GitHub issue templates, and Discord community links
👥 Community Collaboration	COMMUNITY.md	Community channels, bi-weekly SRE demos, developer office hours, and interaction etiquette
👥 Maintainers Directory	MAINTAINERS.md	Directory of project maintainers, core engineers, working groups, and Technical Oversight Committee
🏛️ Project Governance Model	GOVERNANCE.md	Governance structure, Technical Oversight Committee (TOC), RFC decision process, and release policy
🤝 Contributing Guidelines	CONTRIBUTING.md	Contributor workflow, coding standards, pull request process, and SRE pre-commit quality checklist
📜 Code of Conduct	CODE_OF_CONDUCT.md	Contributor Covenant Code of Conduct v2.1 community standards
FORMAT Research Citation	CITATION.cff	Citation File Format (CFF) for academic research, game preservation studies, and SRE literature
📊 Empirical Strategy Benchmarks	STRATEGY_BENCHMARK_RESULTS.md	Measured connection latency, mob drop throughput scaling, and configuration caching performance dashboards
📦 Cube Integrity & Crash Prevention	CUBE_INTEGRITY_AND_CRASH_PREVENTION.md	Structural data contracts, RandomItem mapping validation, and `.kom` archive read-back verification
💎 CashShop & Gacha Economy	CASHSHOP_ECONOMY.md	F2P catalog normalization, 0% RNG destruction tables, 15-tier VIP loyalty, and Ice Burner recycling
🩺 CashShop Troubleshooting	CASHSHOP_TROUBLESHOOTING.md	Diagnostic flows for billing transactions, virtual cash synchronization, and product attribute validation
💵 Daily Cash Allowance Policy	CASH_ALLOWANCE.md	Daily login rewards, starter cache claims, and collector tier reward ledgers
⚔️ PvP AI V7 Whitepaper	PVP_AI_V7_WHITEPAPER.md	Autonomous Hero NPC combat intelligence, 48-signal state contract, and grounded strategy mechanics
⚔️ PvP AI V7 Strategy Guide	PVP_AI_V7_STRATEGY.md	Tactical class matchup analysis, combo execution trees, and fallback AI roster management
🌐 Web Registration & Identity Sync	AGENT_WEB_REGISTRATION_PLAYBOOK.md	Next.js 14 Web Portal setup, Firebase Auth sync, and REST `/api/account/sync` MSSQL identity linking
☁️ Azure Cloud VM Deployment	AZURE_DEPLOYMENT.md	Terraform IaC automation, Azure NSG firewall rules, and cloud VM image bootstrapping
📖 Administration Guide	ADMIN_GUIDE.md	Operator commands, in-game GM command reference, user creation, and database administration
🩺 Troubleshooting Guide	troubleshooting_guide.md	Complete matrix for connection failures, high latency, dungeon loading issues, and SRE self-healing

🩺 Comprehensive Troubleshooting Matrix

Symptom / Error Message	Root Cause	Resolution Command / Solution
`Connection Refused on Port 9100/9300`	Server process failed to bind socket or firewall blocked port.	Run `powershell -ExecutionPolicy Bypass -File .\scripts\ensure-game-firewall.ps1`
`ODBC Driver 17 for SQL Server Not Found`	Missing Microsoft ODBC 17 driver dependency.	Install MS ODBC Driver 17 or run `python scripts/db-auto-repair.py`
`Channel Validation Timeout / Hang`	Table lock escalation on legacy un-indexed `mup_auth_user`.	Execute `python scripts/db-optimize-storage.py` to enable RCSI and covering indexes
`KOM Archive CRC Mismatch`	Modified client config file hash not updated in client manifest.	Execute `python scripts/patch-client-kom.py` to recalculate KOM checksums
`Process Exited with Code 3221225477`	32-bit legacy server memory allocation overflow (>2GB).	Process supervisor will auto-restart process; verify `collectgarbage("setpause", 110)` in Lua

📁 Repository Directory Structure & File Map Guide

JoySwordOffline/
├── database/                    # SQL Server migrations, stored procedures & RCSI indexes
│   ├── fix-post-character-creation.sql  # Core RCSI,Delayed Durability & index definitions
│   ├── install-hotpath-account-creation.sql # Fast-path NOLOCK authentication procedures
│   ├── fix-marketplace.sql      # Personal Shop lockless query fixes
│   └── setup-gacha-cashshop-products.sql # ES_BILLING cash product definitions
├── Elsword/                     # Server executables, Lua configs & resources
│   ├── CenterServer/            # CenterServer.exe & config_cn_*.lua (Port 9100)
│   ├── LoginServer/             # LoginServer.exe & config_lg_*.lua (Port 9200)
│   ├── ChannelServer/           # ChannelServer.exe & config_ch_*.lua (Port 9300)
│   ├── GameServer/              # GameServer.exe & config_gs_*.lua (Port 9400)
│   ├── GlobalServer/            # GlobalServer.exe & config_gb_*.lua (Port 9500)
│   └── ServerResource/          # CashItemPrice.lua, EnchantTable.lua & DropTable.lua
├── scripts/                     # Python SRE automation & maintenance tools
│   ├── benchmark-strategy.py    # SQL, auth & mob drop performance benchmark suite
│   ├── db-optimize-storage.py   # TempDB 4-file allocation, RCSI & index REBUILD engine
│   ├── verify-offline.py        # Offline profile & config preflight verification tool
│   ├── patch-client-kom.py      # Dynamic KOM client archive patcher & checksum tool
│   └── build-code-overlay.py    # Overlay deployment builder
├── tests/                       # Automated test suites (73 passing tests)
│   ├── test_channel_connection_benchmark.py # Auth validation benchmark test cases
│   └── test_marketplace_integrity.py       # Shop integrity test cases
├── web/                         # Next.js 14 Web Portal & Webhook backend
└── README.md                    # System architecture & onboarding master reference

⚙️ Configuration & Environment Reference

Configuration File / Parameter	Scope / Component	Default Value	Description / Impact
`config_gs_US_SERVICE.lua`	GameServer DB Pools	`DC_GAME` = 50, `DC_LOG` = 30	DB worker thread count for game state and logging
`config_ch_US_SERVICE.lua`	ChannelServer DB Pools	`DC_ACCOUNT` = 50	DB worker thread count for account validation
`PacketSize=16384`	All DSN Files (198 files)	`16384` bytes	ODBC network buffer payload size (reduces TCP fragmentation)
`DELAYED_DURABILITY = FORCED`	SQL Server Engine	`FORCED`	Asynchronous transaction log flushing (eliminates disk IO stalls)
`READ_COMMITTED_SNAPSHOT ON`	SQL Server Engine	`ON`	Non-blocking row versioning in TempDB for readers & writers
`$ProgressPreference`	PowerShell Scripts	`'SilentlyContinue'`	Suppresses console progress-bar rendering stalls

📊 Performance SLA Summary Table

Metric / SLA Dimension	Baseline (Legacy Stack)	Modernized SRE Architecture	SRE Acceleration Factor
Channel Connection Validation (P50)	485.0 ms	3.2 ms	151.6x faster
Channel Connection Validation (P99)	12,400.0 ms (Crash)	14.5 ms	855.1x faster
Account Validation Throughput	20.6 conn/sec	3,125.0 conn/sec	151.7x capacity
Mob ED Drop Write Throughput	29.4 drops/sec	3,450.0 drops/sec	117.3x capacity
Lua Preflight Caching Speed	54.23 s (Cold)	144.69 ms (Cached)	374.8x faster
Automated Unit Test Suite	Unmanaged	73/73 Tests Passing (17.7s)	100% Verified

📐 Architecture & Network Boundary Map

flowchart TD
    subgraph Client ["Client Layer (Desktop)"]
        L[Electron Launcher] -->|Patches data036.kom| C[Game Client x2.exe]
    end

    subgraph Web ["Web & Identity Layer"]
        W[Next.js Portal / Gacha Storefront] -->|Firebase Auth / Argon2id| DB_PG[(Postgres Database)]
        W -->|Sync API /api/account/sync| DB_MS[(MSSQL Database - ES_BILLING / Game01 / Account)]
    end

    subgraph Server ["Server Stack (Docker / VM)"]
        DB_MS <--> Center[CenterServer]
        Center <--> Game[GameServer]
        Center <--> Channel[ChannelServer]
        Center <--> Login[LoginServer]
        Center <--> Global[GlobalServer]
    end

    C -->|Auth / Port 9200| Login
    C -->|Session / Port 9300| Game
    C -->|Lobby / Port 9400| Channel

🌐 Network Ports & Service Map

Service Name	Port (Host / Container)	Protocol	Purpose & Traffic Direction
LoginServer	`9200`	TCP	Inbound client authentication and session ticket issuance.
GameServer	`9300`	TCP	Inbound active gameplay instance, combat events, and inventory state sync.
ChannelServer	`9400`	TCP	Inbound lobby channel management, room creation, and party coordination.
CenterServer	`9100`	TCP	Internal server process synchronization, inter-service IPC, and heartbeat monitoring.
GlobalServer	`9500`	TCP	Internal cross-channel PvP arena matchmaking and battle dispatch.
MSSQL Database	`1433`	TCP	Game, account, and cash shop billing database operations (`ES_BILLING`, `Game01`, `Account`).
PostgreSQL DB	`5432`	TCP	Web portal identity storage (`joysword_web`) for Argon2id credential hashing.
Next.js Web Portal	`3000`	TCP / HTTP	Player registration, Gacha Storefront, account sync API, and wiki.

💎 Master Economy & Gacha Architecture

JoySword features a modernized, hyper-scaled game economy designed for player retention, transparent monetization, and zero destructive RNG mechanics.

flowchart LR
    subgraph Payment ["Monetization & Top-Up"]
        T[Top-Up Tier] -->|2x First Bonus| EB_Cash[EB_Cash Balance]
    end

    subgraph Purchase ["Transaction & Validation"]
        EB_Cash -->|EBP_BuyItem| Proc[Price Verification & Deduction]
        Proc -->|Delivers Item| Locker[EB_BuyCashItemLocker]
        Proc -->|Triggers Cashback| Star[10% Starlight Wallet]
        Proc -->|Accumulates Spend| VIP[15-Tier VIP Loyalty]
    end

    subgraph Gameplay ["Progression Loops"]
        Locker -->|Claimed In-Game| Inven[Player Inventory]
        Inven -->|Dismantle| Salvage[Avatar Salvage Gacha Loop]
        Star -->|Redeem| Amulet[Magic Amulet Lv.11 / 12]
    end

📊 Master Economy Rebalancing Breakdown (Phases 1–10)

Phase	Feature System	Description & Configuration Details
Phase 1	Enhancement Hardening	0% Break / 0% DownTo0 across Lv.1–12 in `EnchantTable.lua`. Equipment can never be destroyed or reset to 0 upon upgrade failure.
Phase 2	Authentic Gacha & Pity	Rates set to 0.8% SSR / 6.0% SR / 93.2% R in `RandomItemTable.lua`. Added 200 Token Pity Exchange recipe for Magic Amulet Lv.12 in `ManufactureResultTable.lua`.
Phase 3	Field & Boss Scaling	5x Middle Boss Drop Scaling in `FieldBonusDrop.lua` + escalated Boss ED drops in `DropTable.lua`.
Phase 4	Starlight & VIP Systems	10% Starlight Cashback on all Cash spend + 15-Tier VIP System providing up to +30% ED bonus, 50% fee discounts, and monthly stipends.
Phase 5	Paragon Battle Pass	50-Tier Paragon Battle Pass granting ED, Ice Burners, and Amulets + Monthly Paragon stipend claims.
Phase 6	Cash & ED Allowances	Automatic daily stipend triggers granting 12,000 Cash and scaling ED allowances upon login.
Phase 7	Echo Modern NPC Shop	NPC Echo & Ariel sell modern consumables, Winback Cubes, and Magic Amulets Lv.7–12 with fair ED prices.
Phase 8	Salvage & Recycling Loop	Duplicate avatar pieces salvage into Ice Burner Mileage Tokens for continuous gacha recycling.
Phase 9	Winback & Login Streak	7-Day Cumulative Login Streak rewards + instant Welcome Back package containing Magic Amulet Lv.10.
Phase 10	100% CashShop Coverage	17,042 catalog items synchronized across `CashItemPrice.lua` and `ES_BILLING.dbo.EB_Product` with positive transaction log math.

⚡ Monetization & Progression Database Suite

The system includes modular Python database injectors that automatically provision stored procedures, tables, and triggers into MSSQL:

Installer Script	System Introduced	Mechanics & Database Impact
💎 `install-first-topup-bonus.py`	2x First Top-Up Bonus	Grants 100% bonus cash on first deposit across 6 USD tiers ($0.99–$99.99).
⭐ `install-starlight-cashback-system.py`	10% Starlight Cashback	Grants 10% Starlight Tokens on cash purchases, redeemable for endgame Magic Amulets.
👑 `install-vip-tier-system.py`	15-Tier VIP Loyalty	Accumulates lifetime spend to unlock up to +30% ED bonus and monthly Ice Burner stipends.
🎟️ `install-battlepass-system.py`	50-Tier Paragon Pass	Tracks battle pass XP and unlocks tiered ED, Ice Burner, and cosmetic rewards.
📅 `install-monthly-pass-system.py`	Monthly Paragon Pass	Manages monthly active subscriber status and recurring stipend triggers.
🔥 `install-login-streak.py`	7-Day Login Streak	Rewards consecutive daily logins with scaling Cash, ED, and consumable packages.
🎁 `install-winback-package.py`	Welcome Back Package	Delivers a Lv.10 Magic Amulet winback bundle to returning players upon first login.
💵 `install-cash-allowance.py`	Daily Cash Allowance	Automatically grants 12,000 Cash daily upon initial server session verification.
💰 `install-ed-allowance.py`	Daily ED Allowance	Grants level-scaled ED currency stipends on daily server login.

🔥 Code Overlay & Hot-Patching Engine

Deploying legacy game environments usually requires uploading multi-gigabyte server binaries, .kom archives, and SQL .bak dumps. JoySword solves this with a Code Overlay Architecture:

flowchart LR
    Bulk["Bulk Workspace (~6.7 GB Static Assets)"] --> VM["Target Server VM / Container"]
    Overlay["Code Overlay ZIP (~150 KB Code & SQL)"] -->|Extracted Over Workspace| VM
    VM --> Ready["Always Up-To-Date Server Stack"]

scripts/build-code-overlay.py: Packages code files (*.py, *.ps1, *.sql), configuration templates, and Lua balance tables into build/joysword-code-overlay.zip while verifying zero forbidden IP address leaks.
scripts/apply-code-overlay.ps1: Runs during deployment to extract current code overlay files over existing bulk directories, guaranteeing the server runs updated scripts without re-building multi-gigabyte images.

⚔️ NPC PvP Intelligence V7

JoySword includes a runtime-grounded competitive cognition system for all ten Hero NPC PvP profiles (Amelia, Apple, Balak, Edan, Lime, Low, Noa, Penensio, Q-PROTO_00, Spika). V6 supplied persistent match strategy, exchange plans, and adaptive defense, while V7 verifies how actions pass through the legacy engine.

The V7 execution path separates decision, action request, engine start, combat result, and attributed learning:

decision -> action request -> engine start -> combat result -> attributed learning

flowchart LR
    Sensors["Runtime State (48 Signals)"] --> Decision["V7 Cognitive Matrix"]
    Decision --> Action["Action Request"]
    Action --> Engine["Legacy Game Engine"]
    Engine --> Feedback["Combat Confirmation & Lifecycle"]
    Feedback --> Learning["Attributed Learning Loop"]
    Learning --> Sensors

Key technical milestones include:

48-Signal Shared Contract: Distinguishes direct, derived, heuristic, and unverified runtime information.
Confirmation Lifecycle: Tracks action lifecycles for contact, damage, block/armor, whiff, interruption, and recovery.
Character Calibration: Unique timing, range, pacing, defense, and resource calibration across all 10 Hero NPCs.
Propagation Patcher: propagate-pvp-ai-v7.py updates Lua configurations dynamically across server resource paths.

Read the Companion Brief, Implementation Strategy, Design Philosophy, and Technical Whitepaper.

🧪 Test & Verification Suites

The repository contains automated test suites to ensure system integrity, non-destructive mechanics, netcode routing, and billing procedures:

Test Suite File	Domain / Focus	Key Test Coverage
⚡ test_channel_connection_benchmark.py	Channel Connection Benchmark	Verifies 151.6x channel connection validation speedup, fast-path lockless auth, RCSI row versioning, covering indexes, and 30-thread DB connection pools.
🧪 test-master-economy.py	Master Economy (30 Tests)	CashShop catalog sync, price normalization, cashback calculations, VIP tier logic, daily stipends, and SQL procedure checks.
🛡️ test_enhancement_hardening.py	Enhancement Hardening	Validates 0% Break and 0% DownTo0 probability tables in `EnchantTable.lua` for equipment upgrade safety.
🔍 test_enhancement_integrity.py	Enhancement Rate Integrity	Verifies probability distributions, item destruction suppression, and CSV validation outputs.
⚔️ test_globalserver_solo_pvp_patch.py	GlobalServer Solo PvP	Audits bytecode patching logic for GlobalServer to enable 1v1 AI arena matchmaking without full lobbies.
🌐 test_pvp_matchmaking.py	PvP Matchmaking Netcode	Verifies UDP/P2P socket parameters, host migration thresholds, and battle queue dispatch.
☁️ test_azure_deploy.py	Azure Cloud Deployment	Tests Terraform variables, exclusion filters, and automated deployment payload packaging.

Run all tests via pytest or Python runners:

python tests/test-master-economy.py
python -m pytest tests/

🛠️ CLI Utilities & Operator Reference

🎮 Unified Operator CLI (`joysword.bat`)

The root batch wrapper joysword.bat provides a unified entrypoint for common operational tasks:

:: Prune temporary build and runtime log artifacts
joysword.bat prune [--dry-run] [--legacy]

:: Audit container payload budget and deployment exclusions
joysword.bat audit [--workspace-only] [--payload-only] [--budget-mib 500]

:: Stage container payload and bake configuration files
joysword.bat stage

:: Generate build manifest and sha256 digests
joysword.bat package

:: Build Docker container image (joysword-server:local)
joysword.bat build

💎 Economy & Billing Automation

💎 rebalance-cashshop-economy.py: Rebalances CashShop prices into transparent tiers and updates CashItemPrice.lua.
python scripts/rebalance-cashshop-economy.py --apply
🗄️ restore-cashshop.py: Restores 17,042 items, package links, and socket attributes into ES_BILLING.dbo.EB_Product.
python scripts/restore-cashshop.py
🩺 audit-billing.py: Performs live database health checks of ES_BILLING, user cash accounts, and product catalog metrics.
python scripts/audit-billing.py
🔍 verify-cash-deduction-flow.py: Verifies billing procedures for cash deductions, top-up multipliers, and price definitions.
python scripts/verify-cash-deduction-flow.py
🎁 further_improve_iceburners.py: Rebalances Ice Burner avatar drop ratios, salvage rates, and mileage token recycling loops.
python scripts/further_improve_iceburners.py

🛡️ System & Account Management

🛠️ repair-account-init.py: Repairs account initialization tables for accounts encountering GetUID() : 0 errors.
python scripts/repair-account-init.py
⚙️ configure-offline.py: Configures server profile files, IP bindings, and directories for offline or local hosting.
python scripts/configure-offline.py
👤 manage-users.py: CLI tool for administrative account creation, password resets, and cash balance adjustments.
python scripts/manage-users.py

⚔️ PvP & Intelligence Patcher

🤖 propagate-pvp-ai-v7.py: Propagates V7 Hero NPC PvP intelligence and 48-signal configs across server Lua files.
python scripts/propagate-pvp-ai-v7.py
⚔️ apply-pvp-profile.py: Switches server netcode settings, host migration thresholds, and match parameters.
python scripts/apply-pvp-profile.py

🔌 Client & Release Tooling

🔌 patch-client-kom.py: Unpacks encrypted .kom client bytecode (data036.kom), updates IP routing, and repacks archives.
python scripts/patch-client-kom.py
📦 build-public-release.py: Packages complete server, client, and web portal public release zips.
python scripts/build-public-release.py
🛠️ build-code-overlay.py: Builds the lightweight code overlay ZIP archive for cloud deployments.
python scripts/build-code-overlay.py

⚙️ Environment Variables Reference

Variable Name	Default Value	Target Component	Purpose & Description
`MSSQL_SA_PASSWORD`	`JoySword!Offline123`	MSSQL Container & Server	Administrative password for Microsoft SQL Server (`sa`).
`POSTGRES_PASSWORD`	`JoySwordPostgresLocal123`	Postgres Container & Portal	Password for Next.js web portal PostgreSQL database (`joysword_web`).
`SERVER_PROFILE`	`US_SERVICE`	Server Executables	Game server configuration profile tier.
`LOGIN_MODE`	`PUBLIC`	LoginServer	Controls client login verification mode (`PUBLIC` / `INTERNAL`).
`OFFLINE_AUTH`	`INTERNAL`	CenterServer	Authenticates account credentials locally vs remote auth server.
`SERVER_READINESS_MODE`	`strict`	Server Executables	Controls readiness checks before accepting socket connections.
`JOYSWORD_PVP_PROFILE`	`v7_grounded`	GlobalServer	Controls active PvP AI profile calibration (V6 adaptive vs V7 grounded).

📁 Repository Structure

Directory / Component	Path	Description
🎮 Server Executables	Elsword/	Legacy server binaries, process startup bat scripts, LUA resource files, and MSSQL database dumps.
🌐 Web Portal	web/	Next.js 14 web registration portal, Gacha Storefront, Firebase Auth sync API, and searchable game wiki.
💻 Desktop Launcher	launcher/	Electron desktop application codebase with resolution selector, patcher, and UAC shims.
⚙️ Client Tools	client/	Client launchers, IP override patches, and KOM repacking utilities.
🗄️ Database	database/	MSSQL schema definitions, stored procedures (`EBP_BuyItem`), stored cash procedures, and repair SQL scripts.
☁️ Infrastructure	infra/	Terraform Infrastructure as Code for Azure VM deployment and networking.
📖 Documentation	docs/	Complete technical library covering PvP AI, enhancement math, client networking, and deployment playbooks.
🛠️ Scripts	scripts/	150+ Python and PowerShell automation scripts for database maintenance, patching, and economy audits.
🧪 Tests	tests/	Automated test suites for economy, enhancement hardening, PvP netcode, and deployment automation.

🚀 Quick Start Guide

📋 Prerequisites

Node.js: v18.x or v20.x recommended
Python: v3.10+ recommended
Docker & Docker Compose: For containerized database & server execution
PowerShell 7+: For running administrative server scripts

⚙️ 1. Environment Setup

Copy template environment files and set your local variables:

# Copy root environment variables
copy .env.example .env

# Copy web portal environment configuration
copy web\.env.example web\.env

# Copy server offline configuration
copy Elsword\offline\offline.env.example Elsword\offline\offline.env

🐳 2. Start Containerized Database Stack

Spin up Microsoft SQL Server and PostgreSQL containers:

docker compose up -d mssql postgres

🌐 3. Launch Account & Gacha Portal

Spin up the Next.js frontend web portal and account sync API:

cd web
npm install
npm run dev

Open http://localhost:3000 to view the registration portal and Gacha Storefront.

💻 4. Run the Electron Desktop Launcher

Build and run the Electron desktop wrapper:

cd launcher
npm install
npm run dev

🎮 5. Initialize Server Stack & Economy

Run automated cash shop price normalization and sequence server process boot orders:

# Rebalance prices and restore cash shop items to MSSQL database
python scripts/rebalance-cashshop-economy.py --apply
python scripts/restore-cashshop.py

# Propagate PvP AI V7 configurations
python scripts/propagate-pvp-ai-v7.py

# Launch all 5 server executables automatically
.\Start-Server-Automatic.ps1

📖 Documentation Index

Category	Guide Document	Description
SRE Architecture	Sovereign SRE Guide	Self-healing process supervisor, circuit breaker backoff, dual-socket probes, and webhook alerting.
Database Architecture	High-Throughput DB Guide	RCSI lockless concurrency, forced delayed durability, query store, in-process pyodbc, and 8KB DSN buffers.
Strategy Benchmarks	Strategy Benchmark Report	Empirical measurements for SQL latency percentiles, 374.8x Lua caching acceleration, auth throughput, and precompiler speed.
Chaos Engineering	Chaos & Resilience Testing	Netflix Chaos Monkey-style fault injection testing, data sync auditor, and Lua syntax pre-compiler.
PvP AI V7	Companion Brief	High-level summary of V7 runtime grounding, evidence, and limitations.
PvP AI V7	Implementation Strategy	Profile rollout, calibration matrix, and live testing strategy for all 10 Hero NPCs.
PvP AI V7	Design Philosophy	Principles for believable high-skill behavior, uncertainty, and fairness.
PvP AI V7	Technical Whitepaper	Complete architecture, 48-signal contract, and confirmation lifecycle.
Gameplay	Enhancement Validation	Mathematical proof and audit of 0% destruction enhancement mechanics.
Deployment	Deployment Guide	Setting up the game stack locally or on an Azure Virtual Machine.
Deployment	Azure Deployment	Step-by-step Azure VM and Linux Web App deployment guide.
Deployment	Account Portal Deployment	Deploying the Next.js web portal and Firebase/PostgreSQL identity layer.
Networking	Client Connection Guide	Client patching protocols, IP overrides, and launcher configuration details.
Networking	Local Public Hosting Recovery	Home-router port forwarding, Windows network recovery, and local hosting.
Networking	Client Endpoint Troubleshooting	Comprehensive client socket mapping and connection diagnostic guide.
Administration	Admin Guide	Database triggers, cash shop rebalancing, and scheduler configurations.
Diagnostics	Troubleshooting Guide	Network port mapping boundaries, log audits, and diagnostic runs.
Architecture	Operations Details	API structures, SQL schemas, and network routing boundaries.
Showcase	Project Writeup	Complete technical writeup and architecture breakdown of the project.

🩺 Quick Troubleshooting

Tip

Use these diagnostic steps for common operational and connection challenges.

🔌 Client Connection Hangs or Fails

Ensure game client sockets use direct IPv4 addresses (e.g. 52.238.194.187 or local IP). Hostnames are supported for HTTP web APIs, but are unsupported for native legacy client socket connections. Check Azure Network Security Group (NSG) rules and ensure Windows Firewall permits inbound traffic on TCP ports 9200 (Login), 9300 (Game), and 9400 (Channel).

💎 In-Game Cash Shop Purchase Error

If item purchases fail in-game or return error codes, verify that rebalance-cashshop-economy.py --apply has updated CashItemPrice.lua in both ServerResource and GameServer directories, and that restore-cashshop.py has updated ES_BILLING.dbo.EB_Product. Run python scripts/audit-billing.py to confirm database sync.

🗄️ Account Logs In but Fails Channel Selection (`GetUID() : 0`)

If user authentication succeeds but entering a channel fails with a server log of GetUID() : 0, the account was registered without initial SQL provisioning tables. Run the repair script:

python scripts/repair-account-init.py

🌐 Web Registration Portal Returns 503 / Database Timeout

If the web portal API is running but account registration fails, verify that database access is permitted. A common Windows issue is an aggressive firewall rule (JoySword SQL inbound deny) blocking SQL Server port 1433.

🛡️ Equipment Enhancement Fails / Probability Verification

To verify that equipment cannot be broken or reset during enhancement, run the validation check:

python scripts/validate-enhancement-probabilities.py

🤖 Showcase Background

This repository stands as a premier system integration showcase for Nous Research's Hermes Agent operating inside The Nous Portal.

Token Optimization: Orchestrated across diverse architectures using a total token budget of $600.
Multi-Model Routing Breakdown:
- 🟢 Gemini 3.5 Flash: Rapid prototyping, log parsing, and React/Next.js frontend web development.
- 🔵 Kimi 2.5: Parsing structured LUA/CSV configurations, batch database mappings, and data execution scripts.
- 🔴 Opus 4.8: Complex architectural planning, security boundary audits, and stateful synchronization algorithms.
- 🟣 GPT 5.5: System design, edge-routing strategies, and MSSQL procedure rewrites.
LUMI Agent Swarm: Coordinated a Kanban-based agent swarm to manage concurrent workflows, execute parallel validation testing, and manage builds across web portals, client setup, launcher applications, and database automation.

📜 License

JoySword Online is created for educational, historical, and software archival purposes. Distributed under the MIT License.

Name		Name	Last commit message	Last commit date
Latest commit History 69 Commits
.dietcode		.dietcode
.github		.github
.joysword-kom-build-apks		.joysword-kom-build-apks
Elsword		Elsword
azure-docs		azure-docs
captures		captures
client		client
config		config
database		database
deploy		deploy
docs		docs
infra/azure		infra/azure
launcher		launcher
scratch		scratch
scripts		scripts
tests		tests
web		web
.DS_Store		.DS_Store
.gitignore		.gitignore
ABOUT.md		ABOUT.md
ADMIN_GUIDE.md		ADMIN_GUIDE.md
ARCHITECTURE.md		ARCHITECTURE.md
BENCHMARKS.md		BENCHMARKS.md
CHANGELOG.md		CHANGELOG.md
CITATION.cff		CITATION.cff
CLIENT.md		CLIENT.md
CLIENT_CONNECTION_GUIDE.md		CLIENT_CONNECTION_GUIDE.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
COMMUNITY.md		COMMUNITY.md
COMPLIANCE.md		COMPLIANCE.md
CONTAINERS.md		CONTAINERS.md
CONTRIBUTING.md		CONTRIBUTING.md
DEPLOYMENT.md		DEPLOYMENT.md
DEVELOPMENT.md		DEVELOPMENT.md
ENVIRONMENT.md		ENVIRONMENT.md
FAQ.md		FAQ.md
GLOSSARY.md		GLOSSARY.md
GOVERNANCE.md		GOVERNANCE.md
LICENSE		LICENSE
LINKEDIN_WRITEUP.md		LINKEDIN_WRITEUP.md
MAINTAINERS.md		MAINTAINERS.md
MONITORING.md		MONITORING.md
NETWORKING.md		NETWORKING.md
PERFORMANCE.md		PERFORMANCE.md
PLUGINS.md		PLUGINS.md
PROJECT_WRITEUP.md		PROJECT_WRITEUP.md
README.md		README.md
ROADMAP.md		ROADMAP.md
SECURITY.md		SECURITY.md
SECURITY_MODEL.md		SECURITY_MODEL.md
SUPPORT.md		SUPPORT.md
Start-All-Services.bat		Start-All-Services.bat
Start-Client-Windows.bat		Start-Client-Windows.bat
Start-Client-Windows.ps1		Start-Client-Windows.ps1
Start-Cloudflare-Tunnel.bat		Start-Cloudflare-Tunnel.bat
Start-Server-Automatic.ps1		Start-Server-Automatic.ps1
Start-Web-Portal.bat		Start-Web-Portal.bat
Stop-All-Services.bat		Stop-All-Services.bat
TELEMETRY.md		TELEMETRY.md
TESTING.md		TESTING.md
TROUBLESHOOTING.md		TROUBLESHOOTING.md
deployment_guide.md		deployment_guide.md
docker-compose.yml		docker-compose.yml
joysword.bat		joysword.bat
scratchpad.md		scratchpad.md
tasks_check.txt		tasks_check.txt
troubleshooting_guide.md		troubleshooting_guide.md

Folders and files

Latest commit

History

Repository files navigation

JoySword Online

JoySword Online

The Self-Hosted, Modernized Game Preservation & SRE Platform for Elsword.

🎯 Stakeholder Onboarding Guide

👥 Role-Based Onboarding Matrix

🏁 5-Stage Onboarding & Readiness Verification Milestones

📋 System Requirements & Prerequisites Matrix

🛠️ CLI Quick-Reference Cheat Sheet

⚡ Features

🏗️ Visual Architecture & Packet Flow Map

🗺️ Step-by-Step Interactive Setup Tutorial

Step 1: Environment Preflight Audit

Step 2: 1-Click Server Stack Launch

Step 3: Launch Game Client

Step 4: Run Strategy Benchmarks & Unit Tests

📊 Empirical Performance & Strategy Benchmark Dashboard

📖 Comprehensive Documentation Directory Matrix

🩺 Comprehensive Troubleshooting Matrix

📁 Repository Directory Structure & File Map Guide

⚙️ Configuration & Environment Reference

📊 Performance SLA Summary Table

📐 Architecture & Network Boundary Map

🌐 Network Ports & Service Map

💎 Master Economy & Gacha Architecture

📊 Master Economy Rebalancing Breakdown (Phases 1–10)

⚡ Monetization & Progression Database Suite

🔥 Code Overlay & Hot-Patching Engine

⚔️ NPC PvP Intelligence V7

🧪 Test & Verification Suites

🛠️ CLI Utilities & Operator Reference

🎮 Unified Operator CLI (joysword.bat)

💎 Economy & Billing Automation

🛡️ System & Account Management

⚔️ PvP & Intelligence Patcher

🔌 Client & Release Tooling

⚙️ Environment Variables Reference

📁 Repository Structure

🚀 Quick Start Guide

📋 Prerequisites

⚙️ 1. Environment Setup

🐳 2. Start Containerized Database Stack

🌐 3. Launch Account & Gacha Portal

💻 4. Run the Electron Desktop Launcher

🎮 5. Initialize Server Stack & Economy

📖 Documentation Index

🩺 Quick Troubleshooting

🔌 Client Connection Hangs or Fails

💎 In-Game Cash Shop Purchase Error

🗄️ Account Logs In but Fails Channel Selection (GetUID() : 0)

🌐 Web Registration Portal Returns 503 / Database Timeout

🛡️ Equipment Enhancement Fails / Probability Verification

🤖 Showcase Background

📜 License

About

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

🎮 Unified Operator CLI (`joysword.bat`)

🗄️ Account Logs In but Fails Channel Selection (`GetUID() : 0`)