core2026/docs/architecture/legacy-entities.md

Legacy Entities Overview

This document summarizes the primary entities in the legacy engine, how they interact, and where their state lives. The active runtime lives in legacy/hwe/sammo/ and uses the tables in legacy/hwe/sql/schema.sql.

Data Sources

• Table name map: legacy/hwe/sammo/Enums/TableName.php
• Schema definitions: legacy/hwe/sql/schema.sql

Coverage Notes

• The legacy runtime mixes active, archived, and transitional tables.
• Table relationships are mostly enforced in code; few explicit FK constraints.
• Some tables are retained for history or migration and may not be touched in the current runtime path.

Core Entities

General (장수)

• Class: legacy/hwe/sammo/General.php (base: legacy/hwe/sammo/GeneralBase.php)
• Tables: general, general_turn, rank_data, general_access_log
• Interaction highlights:
  • Command execution: legacy/hwe/sammo/Command/* and legacy/hwe/sammo/TurnExecutionHelper.php
  • Turn reservation: legacy/hwe/sammo/LastTurn.php
  • Combat adapter: legacy/hwe/sammo/WarUnitGeneral.php
  • Modifiers/triggers via iAction modules (items, specials, traits)
  • Logging: legacy/hwe/sammo/ActionLogger.php
• DB fields (schema):
  • general: no, owner, npcmsg, npc, npc_org, affinity, bornyear, deadyear, newmsg, picture, imgsvr, name, owner_name, nation, city, troop, leadership, leadership_exp, strength, strength_exp, intel, intel_exp, injury, experience, dedication, dex1, dex2, dex3, dex4, dex5, officer_level, officer_city, permission, gold, rice, crew, crewtype, train, atmos, weapon, book, horse, item, turntime, recent_war, makelimit, killturn, block, dedlevel, explevel, age, startage, belong, betray, personal, special, specage, special2, specage2, defence_train, tnmt, myset, tournament, newvote, last_turn, aux, penalty
  • general_turn: id, general_id, turn_idx, action, arg, brief
  • general_access_log: id, general_id, user_id, last_refresh, refresh, refresh_total, refresh_score, refresh_score_total
  • rank_data: id, nation_id, general_id, type, value
  • JSON columns: general.last_turn, general.aux, general.penalty

Nation (국가)

• Data rows: nation, nation_env, nation_turn
• Nation-type actions: legacy/hwe/sammo/ActionNationType/*, base in legacy/hwe/sammo/BaseNation.php
• Interaction highlights:
  • Nation commands: legacy/hwe/sammo/Command/Nation/*
  • Diplomacy: diplomacy, ng_diplomacy, and legacy/hwe/sammo/DiplomaticMessage.php
  • Monthly economy updates: legacy/hwe/sammo/Event/Action/*
• DB fields (schema):
  • nation: nation, name, color, capital, capset, gennum, gold, rice, bill, rate, rate_tmp, secretlimit, chief_set, scout, war, strategic_cmd_limit, surlimit, tech, power, spy, level, type, aux
  • nation_turn: id, nation_id, officer_level, turn_idx, action, arg, brief
  • nation_env: id, namespace, key, value
  • JSON columns: nation.spy, nation.aux, nation_turn.arg, nation_env.value

City (도시)

• Data rows: city
• Static map data: legacy/hwe/sammo/CityConstBase.php, legacy/hwe/sammo/CityInitialDetail.php
• Live cache: legacy/hwe/sammo/CityHelper.php
• Interaction highlights:
  • Supply and isolation updates via Event/Action/UpdateCitySupply
  • Conquest/war defender: legacy/hwe/sammo/WarUnitCity.php
• DB fields (schema):
  • city: city, name, level, nation, supply, front, pop, pop_max, agri, agri_max, comm, comm_max, secu, secu_max, trust, trade, dead, def, def_max, wall, wall_max, officer_set, state, region, term, conflict
  • JSON columns: city.conflict

Troop (부대)

• Data rows: troop
• Interaction highlights:
  • Join/leave flows in legacy/hwe/sammo/API/Troop/*
  • Static event hooks from legacy/hwe/sammo/StaticEvent/*
• DB fields (schema):
  • troop: troop_leader, nation, name

Command / Turn (턴 예약과 실행)

• Turn snapshots: legacy/hwe/sammo/LastTurn.php
• General commands: legacy/hwe/sammo/Command/General/*
• Nation commands: legacy/hwe/sammo/Command/Nation/*
• Execution entry: legacy/hwe/sammo/TurnExecutionHelper.php and legacy/hwe/proc.php
• DB fields (schema):
  • general_turn: id, general_id, turn_idx, action, arg, brief
  • nation_turn: id, nation_id, officer_level, turn_idx, action, arg, brief

War Units (전투 단위)

• Base: legacy/hwe/sammo/WarUnit.php
• General combat: legacy/hwe/sammo/WarUnitGeneral.php
• City combat: legacy/hwe/sammo/WarUnitCity.php
• Interaction highlights:
  • Battle flow and resolution: legacy/hwe/process_war.php
  • Uses General/Nation/City snapshots for deterministic resolution

Rule Modules and Modifiers

iAction Modules

• Interface: legacy/hwe/sammo/iAction.php
• Modules:
  • Items: legacy/hwe/sammo/ActionItem/*
  • Domestic specials: legacy/hwe/sammo/ActionSpecialDomestic/*
  • War specials: legacy/hwe/sammo/ActionSpecialWar/*
  • Personalities: legacy/hwe/sammo/ActionPersonality/*
  • Nation types: legacy/hwe/sammo/ActionNationType/*
  • Crew types: legacy/hwe/sammo/ActionCrewType/*
  • Scenario effects: legacy/hwe/sammo/ActionScenarioEffect/*
• Applied by General::getActionList() and used by triggers, stat calculation, and combat phases.

Trigger System

• Trigger callers: legacy/hwe/sammo/TriggerCaller.php, legacy/hwe/sammo/GeneralTriggerCaller.php, legacy/hwe/sammo/WarUnitTriggerCaller.php
• Trigger definitions: legacy/hwe/sammo/GeneralTrigger/*, legacy/hwe/sammo/WarUnitTrigger/*
• Used in pre-turn processing and battle phases.

Constraints

• Validation rules: legacy/hwe/sammo/Constraint/*
• Command prechecks and selection logic use these constraints.

System Entities

Events

• Dynamic events: event table, executed by legacy/hwe/sammo/Event/*
• Static hooks: legacy/hwe/sammo/StaticEvent/*, wired via GameConst::$staticEventHandlers
• DB fields (schema):
  • event: id, target, priority, condition, action
  • JSON columns: event.condition, event.action

Messaging and Diplomacy

• Messages: legacy/hwe/sammo/Message.php
• Targets: legacy/hwe/sammo/MessageTarget.php, legacy/hwe/sammo/Target.php
• Diplomacy wrapper: legacy/hwe/sammo/DiplomaticMessage.php
• Table: message
• DB fields (schema):
  • message: id, mailbox, type, src, dest, time, valid_until, message
  • diplomacy: no, me, you, state, term, dead, showing
  • ng_diplomacy: no, src_nation_id, dest_nation_id, prev_no, state, text_brief, text_detail, date, src_signer, dest_signer, aux
  • JSON columns: message.message, ng_diplomacy.aux

Economy and World State

• Monthly updates: legacy/hwe/sammo/Event/Action/ProcessIncome, ProcessSemiAnnual, ProcessWarIncome
• Trade and supply: RandomizeCityTradeRate, UpdateCitySupply, UpdateNationLevel
• DB fields (schema):
  • nation_env: id, namespace, key, value
  • statistic: no, year, month, nation_count, nation_name, nation_hist, gen_count, personal_hist, special_hist, power_hist, crewtype, etc, aux
  • JSON columns: statistic.aux, nation_env.value

Auctions, Betting, and Votes

• Auctions: legacy/hwe/sammo/Auction.php and ng_auction* tables
• Betting: legacy/hwe/sammo/Betting.php and ng_betting
• Votes and tournaments: vote, vote_comment, tournament
• DB fields (schema):
  • ng_auction: id, type, finished, target, host_general_id, req_resource, open_date, close_date, detail
  • ng_auction_bid: no, auction_id, owner, general_id, amount, date, aux
  • ng_betting: id, betting_id, general_id, user_id, betting_type, amount
  • vote: id, vote_id, general_id, nation_id, selection
  • vote_comment: id, vote_id, general_id, nation_id, general_name, nation_name, text, date
  • tournament: seq, no, npc, name, w, b, h, leadership, strength, intel, lvl, grp, grp_no, win, draw, lose, gl, prmt
  • JSON columns: ng_auction.detail, ng_auction_bid.aux, ng_betting.betting_type, vote.selection

Logs and Records

• Action logs: legacy/hwe/sammo/ActionLogger.php
• User logs: legacy/hwe/sammo/UserLogger.php
• Tables: ng_history, world_history, general_record, user_record, hall
• DB fields (schema):
  • ng_history: no, server_id, year, month, map, global_history, global_action, nations
  • world_history: id, nation_id, year, month, text
  • general_record: id, general_id, log_type, year, month, text
  • user_record: id, user_id, server_id, log_type, year, month, date, text
  • hall: id, server_id, season, scenario, general_no, type, value, owner, aux
  • JSON columns: ng_history.map, ng_history.global_history, ng_history.global_action, ng_history.nations, hall.aux

Boards, Locks, and Storage

• Boards/comments: board, comment
• Locks: plock
• KV stores: storage, nation_env
• DB fields (schema):
  • board: no, nation_no, is_secret, date, general_no, author, author_icon, title, text
  • comment: no, nation_no, is_secret, date, document_no, general_no, author, text
  • plock: no, type, plock, locktime
  • storage: id, namespace, key, value
  • JSON columns: storage.value

Archive and Lifecycle Tables

• Archive/season data: ng_games, ng_old_nations, ng_old_generals, emperior
• Scheduling: reserved_open
• Selection pools: select_npc_token, select_pool
• Inheritance: inheritance_result
• DB fields (schema):
  • ng_games: id, server_id, date, winner_nation, map, season, scenario, scenario_name, env
  • ng_old_nations: id, server_id, nation, data, date
  • ng_old_generals: id, server_id, general_no, owner, name, last_yearmonth, turntime, data
  • emperior: no, server_id, phase, nation_count, nation_name, nation_hist, gen_count, personal_hist, special_hist, name, type, color, year, month, power, gennum, citynum, pop, poprate, gold, rice, l12name, l12pic, l11name, l11pic, l10name, l10pic, l9name, l9pic, l8name, l8pic, l7name, l7pic, l6name, l6pic, l5name, l5pic, tiger, eagle, gen, history, aux
  • reserved_open: id, options, date
  • select_npc_token: id, owner, valid_until, pick_more_from, pick_result, nonce
  • select_pool: id, unique_name, owner, general_id, reserved_until, info
  • inheritance_result: id, server_id, owner, general_id, year, month, value
  • JSON columns: ng_games.env, ng_old_nations.data, ng_old_generals.data, emperior.history, emperior.aux, reserved_open.options, select_npc_token.pick_result, inheritance_result.value

Aux and JSON Payloads

Legacy data uses many JSON fields with dynamic keys. Most are updated in code, not enforced by DB constraints.

General aux

• Storage layer: legacy/hwe/sammo/LazyVarAndAuxUpdater.php
• Access pattern: getAuxVar() / setAuxVar() on General
• Literal keys observed in code (not exhaustive):
  • armType, autorun_limit, inheritBuff, inheritRandomUnique, inheritResetSpecialWar, inheritResetTurnTime, inheritSpecificSpecialWar, last발령, max_domestic_critical, movingTargetCityID, nextTurnTimeBase, pickYearMonth, use_auto_nation_turn, use_treatment
• Key sources:
  • Turn execution timing: legacy/hwe/sammo/TurnExecutionHelper.php
  • AI state and movement: legacy/hwe/sammo/GeneralAI.php
  • Inheritance actions: legacy/hwe/sammo/API/InheritAction/*
  • Domestic critical resets: legacy/hwe/sammo/Command/General/*
  • Troop dispatch markers: legacy/hwe/sammo/Command/Nation/che_발령.php
• Item or trigger-specific keys are stored via constants (e.g. ActionItem/event_충차.php, WarUnitTrigger/event_충차아이템소모.php) and are not visible in literal scans.

Nation aux

• Enum keys: legacy/hwe/sammo/Enums/NationAuxKey.php
  • can_국기변경, can_국호변경, did_특성초토화, can_무작위수도이전, can_대검병사용, can_극병사용, can_화시병사용, can_원융노병사용, can_산저병사용, can_상병사용, can_음귀병사용, can_무희사용, can_화륜차사용
• Used by constraints and nation commands, especially unit unlock logic.

Other JSON Columns

• city.conflict: siege contribution map keyed by nation id.
• message.message: serialized message payload including targets/options.
• event.condition / event.action: JSON DSL for event dispatch.
• storage.value / nation_env.value: key-value JSON via KVStorage (legacy/src/sammo/KVStorage.php), used for game_env, nation_env, betting, vote, inheritance_*, and other namespaces.
• Large history blobs: ng_history.*, ng_old_nations.data, ng_old_generals.data, emperior.history, emperior.aux.

KVStorage game_env Namespace

game_env is stored in storage with namespace = 'game_env' and is the primary server-wide runtime state store. Keys are read/written in core functions and APIs (e.g. legacy/hwe/func.php, legacy/hwe/func_time_event.php, legacy/hwe/sammo/TurnExecutionHelper.php).

Observed literal keys (from code reads/writes, non-exhaustive):

• Time and turn: startyear, year, month, init_year, init_month, starttime, opentime, turntime, turnterm
• Scenario and season: scenario, scenario_text, season
• Join and creation gates: join_mode, maxgeneral, block_general_create, show_img_level, icon_path, extended_general
• Global flags and limits: isunited, fiction, autorun_user, killturn, refresh, maxrefresh, refreshLimit, maxonline, recentTraffic, online_user_cnt, online_nation, server_cnt, msg
• NPC policy: npcmode, npc_nation_policy, npc_general_policy
• Tournament and voting: tournament, phase, tnmt_type, tnmt_time, tnmt_auto, tnmt_msg, tnmt_trig, tnmt_pattern, develcost, last_tournament_betting_id, lastVote
• Scout restrictions: block_change_scout
• Auctions: obfuscatedNamePool

Notes:

• Some keys are used as feature toggles (e.g. block_change_scout, block_general_create) while others carry time/season state.
• Additional keys may exist via dynamic or computed names outside literal scans, especially in admin or migration scripts.

Table Usage Index (Partial)

This index focuses on primary runtime touch points and omits view-only pages.

• general: legacy/hwe/sammo/General.php, legacy/hwe/sammo/GeneralAI.php, legacy/hwe/sammo/TurnExecutionHelper.php
• general_turn: legacy/hwe/sammo/TurnExecutionHelper.php, legacy/hwe/sammo/API/Command/GetReservedCommand.php
• general_access_log: legacy/hwe/sammo/General.php, legacy/hwe/sammo/API/General/GetFrontInfo.php
• rank_data: legacy/hwe/sammo/General.php, legacy/hwe/sammo/WarUnitGeneral.php
• nation: legacy/hwe/sammo/Command/Nation/*, legacy/hwe/sammo/Scenario/Nation.php
• nation_turn: legacy/hwe/sammo/TurnExecutionHelper.php, legacy/hwe/sammo/API/NationCommand/GetReservedCommand.php
• nation_env: legacy/src/sammo/KVStorage.php, legacy/hwe/sammo/Command/NationCommand.php
• city: legacy/hwe/sammo/CityHelper.php, legacy/hwe/sammo/WarUnitCity.php, legacy/hwe/process_war.php
• troop: legacy/hwe/sammo/API/Troop/*, legacy/hwe/sammo/StaticEvent/*
• diplomacy, ng_diplomacy: legacy/hwe/sammo/DiplomaticMessage.php, legacy/hwe/sammo/API/Global/GetDiplomacy.php
• message: legacy/hwe/sammo/Message.php, legacy/hwe/sammo/API/Message/*
• event: legacy/hwe/sammo/TurnExecutionHelper.php, legacy/hwe/sammo/Event/*
• board, comment: legacy/hwe/v_board.php, legacy/hwe/j_board_get_articles.php
• ng_auction, ng_auction_bid: legacy/hwe/sammo/Auction.php, legacy/hwe/sammo/API/Auction/*
• ng_betting: legacy/hwe/sammo/Betting.php, legacy/hwe/sammo/API/Betting/*
• vote, vote_comment: legacy/hwe/sammo/API/Vote/*, legacy/hwe/v_vote.php
• ng_history, world_history: legacy/hwe/sammo/ActionLogger.php, legacy/hwe/func_history.php
• general_record: legacy/hwe/sammo/ActionLogger.php
• user_record: legacy/hwe/sammo/UserLogger.php
• storage: legacy/src/sammo/KVStorage.php, legacy/hwe/sammo/ResetHelper.php
• ng_games, ng_old_nations, ng_old_generals, emperior: legacy/hwe/sammo/ResetHelper.php, legacy/hwe/a_emperior.php

Interaction Sketch

• Turn execution (TurnExecutionHelper):
  • Reads general_turn / nation_turn
  • Builds General/Nation/City context
  • Applies constraints → runs command → triggers → logs
  • Runs monthly events and world updates
• Battle (process_war.php):
  • Builds WarUnitGeneral and WarUnitCity
  • Resolves phases and damage with triggers
  • Applies city conquest and nation collapse rules
• Diplomacy:
  • Message delivers a diplomacy request
  • DiplomaticMessage accepts/rejects
  • Nation command executes and updates diplomacy tables

Entity Relationships (Mermaid ERD)

Note: message.src / message.dest are polymorphic in practice (general or nation depending on message type). The diagram below treats them as general links for simplicity.

erDiagram
    GENERAL ||--o{ GENERAL_TURN : reserves
    GENERAL ||--o{ GENERAL_ACCESS_LOG : logs
    GENERAL ||--o{ GENERAL_RECORD : records
    GENERAL ||--o{ RANK_DATA : ranks
    GENERAL ||--o{ MESSAGE : sends
    GENERAL ||--o{ MESSAGE : receives
    GENERAL ||--o{ VOTE : votes
    GENERAL ||--o{ VOTE_COMMENT : comments
    GENERAL ||--o{ NG_BETTING : bets
    GENERAL ||--o{ NG_AUCTION : hosts
    GENERAL ||--o{ NG_AUCTION_BID : bids
    GENERAL ||--o{ TROOP : leads

    NATION ||--o{ GENERAL : has
    NATION ||--o{ NATION_TURN : schedules
    NATION ||--o{ CITY : owns
    NATION ||--o{ DIPLOMACY : relates
    NATION ||--o{ NG_DIPLOMACY : documents
    NATION ||--o{ BOARD : boards
    NATION ||--o{ COMMENT : comments
    NATION ||--o{ WORLD_HISTORY : history

    CITY ||--o{ GENERAL : hosts

    BOARD ||--o{ COMMENT : comments

    NG_AUCTION ||--o{ NG_AUCTION_BID : bids

Related Docs

• docs/architecture/legacy-engine.md
• docs/architecture/legacy-engine-general.md
• docs/architecture/legacy-engine-war.md
• docs/architecture/legacy-engine-economy.md
• docs/architecture/legacy-engine-diplomacy.md
• docs/architecture/legacy-engine-events.md