Patterns
Package Atlas: What Lives Where
One pass through every top-level package in commons/ and gameserver/.
commons/ - shared infra, no game knowledge
commons/
config/ typed config-file readers
crypt/ Blowfish, NewCrypt, login key gen
database/ HikariCP DataSource, connection borrowing
network/ Selector-based reactor:
• ConnectionManager — accepts sockets
• NetClient / NetServer
• IIncomingPacket / IOutgoingPacket bases
Game and Login servers both subclass these.
threads/ ThreadPool (general + scheduled)
time/ TimeUtil, cron-like helpers
ui/ shared Swing pieces
util/ IXmlReader, Rnd, StringUtil, HexUtil, ConfigReader
Rule: commons must never import from gameserver/ or loginserver/.
It is the "kernel" layer.
gameserver/entity/ - the domain model (the nouns)
entity/
World.java ◄─ global singleton: all WorldObjects,
region grid, broadcasting, lookups
WorldObject.java ◄─ root of everything that exists in-world
WorldRegion.java ◄─ spatial bucket
Location.java ◄─ (x,y,z,heading) value type
actor/ ◄─ Creature, Player, Npc, Attackable,
Summon, Playable, Vehicle, Tower
+ actor/stat/ + actor/status/
+ actor/instance/ (per-NPC subclasses)
+ actor/templates/, /tasks/, /transform/
clan/ ◄─ Clan, ClanMember, ClanWar, alliances
cubic/ ◄─ cubic summon effects on players
groups/ ◄─ Party, CommandChannel, MatchingRoom
item/ ◄─ Item, Weapon, Armor, EtcItem domain
itemcontainer/ ◄─ Inventory, Warehouse, PetInventory, Mail
residences/ ◄─ Castle, Fort, ClanHall, Conquerable*
instancezone/ ◄─ Instance world wrapper + templates
shuttle/ ◄─ shuttle vehicle model
spawns/ ◄─ spawn point + template structures
teleporter/ ◄─ teleport list / route nodes
zone/ ◄─ PvP, peace, water, siege, drop zone, ...
Most code outside entity/ is verbs acting on these nouns.
gameserver/managers/ - long-lived subsystem singletons (~50)
See the Patterns page for the full list and shape.
gameserver/mechanics/ - gameplay rule modules
Not just math - whole game systems. Pairs with a matching manager (long-lived state) and a matching set of network packets (client surface).
mechanics/
alchemy/ commission/ olympiad/
announce/ conditions/ options/
beautyshop/ effects/ petition/
buylist/ ensoul/ primeshop/
captcha/ events/ punishment/
clientstrings/ fishing/ script/
herobook/ siege/
homunculus/ skill/
html/ stats/
krateisCube/ undergroundColiseum/
variables/
Example pairing:
mechanics/olympiad/ = the rules of an Olympiad match
managers/OlympiadManager = the running tournament's state
network/.../olympiad pkts = how the client sees it
gameserver/network/ - wire protocol
network/ ConnectionState.java handshake/connected/in-game FSM Encryption.java per-session crypt BlowFishKeygen.java session key generation GameClient.java per-socket player context GamePacketHandler.java opcode ─► packet factory ClientPackets.java opcode table (inbound) ExClientPackets.java extended opcode table ServerPackets.java opcode table (outbound) SystemMessageId.java client-side string ids NpcStringId.java NPC dialogue string ids ClientString.java versioned client strings PacketLogger.java dev-only wire dump Disconnection.java graceful kick path clientpackets/ RequestEnterWorld, RequestUseItem, ... serverpackets/ CharInfo, SystemMessage, UserInfo, ... loginserverpackets/ packets over LoginServerThread enums/ packet-side enums holders/ network-layer DTOs
gameserver/scripting/ - runtime Java compiler
scripting/
ScriptEngine.java compiles dist/data/scripts/**/*.java
at boot using javax.tools.JavaCompiler
engine/ classloader + cache for compiled scripts
annotations/ @ScriptEngine, @Reload tags
gameserver/taskmanagers/ - ticking subsystems
Each one is a singleton holding a list of subjects plus a single scheduled tick that walks the list. Cheap per-creature work (movement step, follow-target check, attack timing) lives here, not in per-entity threads - that keeps the thread count flat as the world grows.
taskmanagers/ AttackStanceTaskManager MovementTaskManager AttackableThinkTaskManager PlayerAutoSaveTaskManager AutoPlayTaskManager PvpFlagTaskManager AutoPotionTaskManager RandomAnimationTaskManager AutoUseTaskManager RespawnTaskManager BuyListTaskManager ... CreatureAttackTaskManager CreatureFollowTaskManager CreatureSeeTaskManager DecayTaskManager GameTimeTaskManager ItemAppearanceTaskManager ItemLifeTimeTaskManager ItemManaTaskManager ItemsAutoDestroyTaskManager MessageDeletionTaskManager
gameserver/ui/ - operator console
ui/ Gui.java Swing frame embedding... LogPanel.java ...live tail of the server log SystemPanel.java ...CPU / mem / online players / GC info AboutFrame.java version / credits dialog Optional. Headless mode skips it.
gameserver/util/ - leaf helpers (no upward deps)
util/ ArrayUtil, MathUtil, MapUtil, LocationUtil ◄ collections/math StatSet ◄ typed key-value bag DocumentBase, DocumentItem ◄ XML parser bases FloodProtector* ◄ per-action throttles GMAudit ◄ admin action log GeoUtils, PolygonTerritory ◄ geometry helpers HtmlUtil ◄ in-game HTML helpers DeadlockWatcher ◄ thread watchdog DXT1ImageCompressor, PrimeCapacityAllocator ◄ niche helpers Locator ◄ service locator Rule: util/ only depends on JDK + commons. Never the other way.
How a single mob action exercises every package
GameTimeTaskManager fires "world tick"
│
▼
taskmanagers/AttackableThinkTaskManager
│ (selects mobs near players)
▼
entity/actor/Attackable.getAI() ─► ai/* implementation
│
▼
AI decides "cast skill"
│
▼
mechanics/skill + mechanics/stats + util/MathUtil
│
▼
mechanics/effects applies buffs/damage to entity/actor/Creature
│
▼
network/serverpackets/* pushed via GameClient
│
▼
commons/network selector writes encrypted bytes to socket
│
▼
managers/* (e.g. SiegeManager) notified if target/zone cares
│
▼
data/sql/* persists side effects (clan rep, items, ...)
In one line:
taskmanager ─► entity.actor ─► ai ─► mechanics ─► network ─► managers ─► data/sql