JoySword Online

The self-hosted, modernized game preservation stack for JoySword (Elsword).

Quick Start • Architecture • Features • Documentation • Troubleshooting • Agentic Showcase

_{Built for developers, gaming historians, and private server administrators.}

---

⚡ Features

• ⚡ Core Server Stack: Local or containerized execution of the five legacy server executables (Center, Game, Channel, Login, Global) bundled with an optimized SQL Server database.
• 🛡️ Identity Sync Engine: Bridges modern user authentication (Argon2id hashing via Next.js + PostgreSQL) directly with legacy game database structures (MSSQL) in real-time.
• 🔌 Dynamic Client Patching: Custom Python algorithms to dynamically override client IP routing tables and repack .kom bytecode packages (data036.kom) on startup.
• 💻 Electron Desktop Launcher: A ready-to-run Windows client wrapper that applies resolutions, launches processes, and bypasses UAC flags using shims.
• ☁️ Infrastructure as Code: Terraform configurations to deploy the entire environment securely to Azure VMs with VNet-isolated networking.
• 📊 Economy Rebalancer: Scripted tooling to audit, normalize, and scale in-game currency flows, cash shop lists, and costume unlock mechanics.

---

📐 Architecture Overview

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 / Wiki] -->|Argon2id Hash| DB_PG[(Postgres Database)]
        W -->|Sync Credentials| DB_MS[(MSSQL Database)]
    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

Loading

---

NPC PvP Intelligence V7

JoySword now includes a runtime-grounded competitive cognition system for all ten Hero NPC PvP profiles. V6 supplies persistent match strategy, exchange plans, tactical intentions, opponent hypotheses, conditioning, combo judgment, adaptive defense, and character-specific playbooks. V7 verifies how those decisions pass through the legacy engine before allowing the bots to learn from their outcomes.

The V7 execution path separates five questions that older reactive AI commonly conflates:

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

Key improvements include:

• A shared 48-signal contract distinguishing direct, derived, heuristic, unverified, and unavailable runtime information.
• Expiring observations with source, confidence, and action attribution.
• A bounded action lifecycle for start, contact, damage, block/armor, whiff, interruption, rejection, timeout, recovery, and uncertain results.
• Character-specific timing, range, pacing, defense, resource, and identity calibration for Amelia, Apple, Balak, Edan, Lime, Low, Noa, Penensio, Q-PROTO_00, and Spika.
• Separate decision, execution, confirmation, tactical, and strategic failure handling so engine rejection cannot incorrectly retrain match strategy.
• Optional bounded telemetry, route memory, repetition analysis, occupancy metrics, dormant-action coverage, and counterfactual diagnostics.

Offline validation completed 300 deterministic scenarios and 64,000 decision ticks across the roster. In the V7 engine approximation, all 1,237 requested actions reached terminal lifecycle states while telemetry remained capped at 96 entries and route memory at 48. These results establish offline calibration readiness; they do not claim live collision, timing, or human-like gameplay validation.

Read the companion brief for the concise overview, the implementation strategy for rollout and calibration guidance, the design philosophy for the fairness and intelligence principles, and the technical whitepaper for architecture and evidence.

---

📁 Repository Structure

Component	Path	Description
🎮 Server	Elsword/	Executable files, log configurations, and database backups.
🌐 Portal	web/	Next.js authentication portal, site files, and searchable wiki.
💻 Launcher	launcher/	Desktop Electron app codebase.
⚙️ Client	client/	Windows client scripts, patches, and launchers.
🗄️ Database	database/	MSSQL routines, cash-allowance structures, and SQL audits.
☁️ Infra	infra/	Azure VM and network deployment scripts.
🛠️ Scripts	scripts/	PowerShell & Python tasks for patches, audits, and configuration.
🧪 Tests	tests/	Validation checks for database connection configurations.

---

🚀 Quick Start Guide

📋 Prerequisites

• Node.js (v18.x or v20.x recommended)
• Python (v3.10+ recommended)
• Microsoft SQL Server / PostgreSQL (for local runs)

⚙️ 1. Environment Configuration

Before launching services, copy the environment templates and insert your local or staging variables:

• Root Settings: Copy .env.example to .env in the root folder.
• Web Settings: Copy web/.env.example to web/.env.
• Server Settings: Copy Elsword/offline/offline.env.example to Elsword/offline/offline.env.

🌐 2. Start the Account Portal

Spin up the Next.js frontend and registration API:

cd web
npm install
npm run dev

Access the portal at http://localhost:3000.

💻 3. Run the Electron Desktop Launcher

Compile and boot the Electron wrapper client:

cd launcher
npm install
npm run dev

🎮 4. Initialize Server Executables (Windows / VM)

Bootstrap database procedures, adjust firewall rules, and sequence server process boot orders:

.\Start-Server-Automatic.ps1

---

📖 Documentation Index

Guide	Description
NPC PvP Intelligence V7 Companion Brief	Concise summary of the runtime-grounding milestone, evidence, limitations, and recommended next step.
NPC PvP Intelligence V7 Strategy	Implementation, calibration, change-control, and live-testing strategy for all ten Hero NPC profiles.
NPC PvP Intelligence V7 Design Philosophy	Principles for believable high-skill behavior, uncertainty, fairness, identity, bounded adaptation, and anti-cheating.
NPC PvP Intelligence V7 Whitepaper	Technical architecture, signal contract, confirmation lifecycle, harness methodology, exact offline results, and evidence boundaries.
Local Public Hosting Recovery	Home-router port forwarding, Windows network recovery, and local public-host troubleshooting.
🚀 Deployment Guide	Setting up the game stack locally or on an Azure Virtual Machine.
🔌 Connection Guide	Client patching protocols, IP overrides, and launcher configuration details.
👑 Admin Guide	Database triggers, rebalancing cash shops, and scheduler configurations.
🩺 Troubleshooting Guide	Network port mapping boundaries, log audits, and diagnostic runs.
📝 Operations Details	API structures, SQL schemas, and network routing boundaries.

---

🩺 Quick Troubleshooting

Tip

Use these quick checks for common setup and deployment hurdles.

🔌 Client Cannot Connect / Login Hangs

Ensure game client sockets use direct IPv4 only (52.238.194.187). Hostnames are supported for HTTP/web APIs, but are unsupported for client game connections. Check Azure NSG rules and verify Windows Firewall is permitting inbound traffic on TCP ports 9200, 9300, and 9400.

🗄️ Account Enters Login but Fails Channel Selection

If user verification succeeds but entering a channel fails with a server log of GetUID() : 0, the account was created without its SQL provisioning tables. Use the database repair utility to resolve this:

python scripts/repair-account-init.py

🌐 Web Registration Portal Returns 503

If the API is healthy but registration fails, verify that database access is not being blocked. A common issue is a Windows Firewall rule JoySword SQL inbound deny blocking SQL Server port 1433 even if VNet routes are configured correctly.

---

🤖 Showcase Background

This repository stands as an automated 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: Hermes divided system tasks between specialized models:
  • Gemini 3.5 Flash for rapid prototyping, logs parsing, and React development.
  • Kimi 2.5 for parsing structured configurations and executing data steps.
  • Opus 4.8 for network auditing and security boundaries.
  • GPT 5.5 for top-level service configurations and database schema migrations.
• LUMI Swarm: Utilized a Kanban-based agent swarm to orchestrate simultaneous validation testing across web portals, client setup, and launcher builds.

---

_{JoySword Online is created for educational, historical, and software archival purposes.}