Architecture

The GameServer Boot Sequence

What that long startup log is actually doing, in order.

   1. Banner / JVM info / Toolkit warmup
   2. Set up logging  (log.cfg ─► java.util.logging)
   3. ConfigLoader      ◄─ reads dist/game/config/*.ini  + *.xml
   4. ThreadPool        ◄─ scheduled + general executors
   5. DatabaseFactory   ◄─ HikariCP pool against MySQL
   6. IdManager         ◄─ claims free object IDs from DB
   7. World             ◄─ the huge in-memory grid (regions, objects)
   8. Data loaders (XML):  ItemData, SkillData, NpcData, MapRegionData,
                           DoorData, FenceData, MultisellData, ...
                       ◄─ parses dist/data/*.xml into singletons
   9. Data loaders (SQL):  ClanTable, AnnouncementsTable, OfflinePlayTable
  10. Managers           CastleManager, FortManager, OlympiadManager,
                         RaidBossSpawnManager, DailyResetManager, ...
  11. Handlers           AdminCommandHandler, ItemHandler, ChatHandler,
                         EffectHandler, ConditionHandler, ...
  12. Scripts            quests/, events/, ai/ ─ compiled at runtime
  13. GeoEngine          loads dist/data/geodata pathfinding cells
  14. ConnectionManager  binds GamePacketHandler to TCP 7777
  15. LoginServerThread  connects out to LoginServer, registers GS id
  16. Shutdown hook      flushes DB, notifies players, saves offline

ConfigLoader ──► ThreadPool ──► DatabaseFactory ──► IdManager
                                       │
                                       ▼
                                     World
                    ┌──────────────────┘  └───────────────┐
                    ▼                                  ▼
              XML loaders                          SQL loaders
                    │                                  │
                    └─────────────┴───────────────────────┘
                                 ▼
                             Managers ──► Handlers
                                 │            │
                                 ▼            ▼
                          Scripts (runtime compile)
                                 │
                                 ▼
                       GeoEngine + Network bind
                                 │
                                 ▼
                       "ready, accepting clients"

What the order tells you

The boot order is not arbitrary. Each step depends on the ones above it being fully initialized:

  • Config first. Nothing can use a port number, a thread-pool size, or a JDBC URL before ConfigLoader finishes.
  • Threads before DB. The pool that runs query callbacks must exist before the pool that runs queries.
  • DB before IdManager. Object IDs are reserved against the database.
  • World before data. The grid that holds NPCs has to exist before the NPC data is parsed and instantiated.
  • Data before managers. A manager that looks up items must wait for ItemData to be loaded.
  • Managers before scripts. A quest that spawns a raid boss needs RaidBossSpawnManager ready.
  • Scripts before network bind. Quests must be registered before the first client packet can fire onTalk.

Where boots go wrong

If the GameServer hangs or crashes on startup, the log line right before the failure tells you which phase failed:

  • "DatabaseFactory failed" - MySQL service not running, wrong JDBC URL, or schema not installed.
  • "ItemData failed" - malformed XML under dist/data/stats/items/.
  • "Script compilation failed" - a quest in dist/data/scripts/ has a Java syntax error.
  • "GeoEngine failed" - missing or corrupt geodata files under dist/data/geodata/.

Restart with the offending file fixed and the next phase resumes.