GearN Server

GearN Server is a Node.js and TypeScript backend package for game-oriented server features such as authentication, player data, group systems, inventory, content, store inventory, dashboard administration, multiplayer matchmaking, cloud script, HTTP APIs, and Socket.IO realtime events.

Repository Role

This repository is both:

• The source code of the GearN server runtime.
• The package source exported through src/index.ts and published from dist/index.js.

Main Entry Points

• Package export entry: src/index.ts
• Runtime startup class: src/GN-startup/ServerApplicationStartup.ts
• Runtime assembly: src/GN-startup/ServerApplication.ts
• Core server coordinator: src/GNServer.ts
• Local debug runner: index.js
• Local runtime config: GNconfig.debug.json

Folder Map

• src/GN-startup: startup, transport, middleware, settings, upload, cluster, and cloud script templates
• src/GN-app-api: request handlers and integration services
• src/GN-common: request and response contracts, enums, constants, helpers
• src/GN-library: internal utilities for database, settings, time, random, debug, and builders
• dist: compiled output used by the local runner and package consumers

Quick Start

1. Install dependencies with npm install.
2. Update GNconfig.debug.json for your local database and runtime ports.
3. Build the runtime with npm run build.
4. Start the local debug server with npm run debug.

Runtime Flow

1. index.js loads GNconfig.debug.json.
2. ServerApplicationStartup converts raw config into typed settings objects.
3. ServerApplication wires Express, Socket.IO, middleware, upload handling, cluster handling, database setup, and GNServer.
4. GNServer.init() registers request handlers through RequestControllerUtils.addAllHandler.
5. HTTP or socket requests are converted into Request objects and dispatched by RequestController.

Transport Contracts

• HTTP JSON route: POST /api/json/:requestType/:role/:operationCode
• HTTP MsgPack route: POST /api/msgpack/:requestType/:role/:operationCode
• Health endpoints: GET /ping, POST /ping, GET /healthcheck
• Socket auth event: Commands.RequestAuthTokenCmd
• Socket request events: Commands.RequestCmd_Json and Commands.RequestCmd_MsgPack

Project Docs For AI

• AGENTS.md: repo-specific rules for AI agents
• ARCHITECTURE.md: startup flow, module boundaries, data flow, and extension points
• DEVELOPMENT.md: build commands, config sections, workflow, and current caveats
• DOMAIN_RELATIONSHIP.md: domain map and relationships between authenticate, player, group, inventory, store inventory, content, dashboard, matchmaking, and cloud script
• CLOUDSCRIPT_USAGE.md: CloudScript overview, runtime rules, helper selection, and links to split helper docs
• docs/MATCHMAKING_TEST_PLAN.md: direct unit-test plan for matchmaking candidate generation and every queue rule type

Third-Party Dependencies

This project uses open source libraries. License details are listed in THIRD_PARTY_LICENSES.