Skip to content

BigWorld to Apollo Concept Mapping ​

This page maps BigWorld 14.4.1 server terms to Apollo processes, objects, and code, distinguishing partial responsibility matches, project gameplay, and missing implementation. Keep gateway, loginServer, baseServer, worldServer, database, and machined. The discussed cell execution process corresponds to CellApp; uppercase Cell means a spatial partition.

1. Process responsibilities ​

BigWorldApollo counterpartResponsibility and differenceImplementation boundary
LoginAppAuthentication in loginServerLogin ingress/authentication; Apollo also hosts service/online directories here.Existing login primitives; final Base/cell wiring incomplete.
BaseAppbaseServerPersistent non-spatial logic; base::Avatar implements the player profile side. Base is not the database process.apps/base provides the standalone base entry with Avatar activation through remote database. Base gameplay and settlement admission are wired; directory ownership remains pending.
Relevant BaseAppMgr dutiesBase registration, placement, and directories in loginServerReuse responsibility boundaries without claiming a full BaseAppMgr implementation.Base registration/ownership/recovery pending.
Relevant CellAppMgr dutiesworldServerManage cell processes, Space/Cell assignment, capacity, topology, drain, and transfer; no per-entity simulation loop.Execution kernel extracted from WorldApp (CellApp owns the simulation loop, Scene, AOI, combat and Lua; WorldApp keeps the management admission face and embeds the kernel); the cell registration admission face is landed (contract 960/961 raw frames with an epoch-adjudicating registry, see the L101 first slice in the root todo); process management, Space/Cell assignment, capacity declaration and topology versioning remain pending.
CellAppcell execution processHost local Cells of one or more Spaces; advance entities, AOI, combat, scripts, and ticks.The kernel runs from the standalone cellServer entry (intent admission only; world --role=cell is explicitly rejected and points to cellServer); both registration faces and heartbeat expiry are landed — World-side admission (960's ten self-declared fields recorded — including the contract-compat projection (kInternalHash folded to int64 via FNV-1a 64), which the World adjudicates must equal its own value or rejects (mismatch or undeclared 0) with code 5; 961 echoing the management epoch with an adjudication code; raw-frame admission as with 944/952/956, auth credentials tracked in the world-cell-management gap table) and cell-side active dialing (--register-host/--register-port/--cell-id, registering on link-up transitions, idempotent refresh on re-dial); periodic heartbeats keep the entry alive (default 5s 960 re-send) and the World-side expiry window drops stale entries (--cell-expiry-ms, default 30s — dropped entirely when the window lapses, re-registration admitted as a fresh registration); the multi-Space declaration face is landed (--add-space <id>:<name> wired at the startup window, one scene and route per Space, instance-less); the World allocation face is landed (contract 962 cell_space_assign — the --assign-spaces pool is claimed exclusively by the lightest-load eligible cell (unready or draining cells claim nothing new while their existing assignments keep refreshing — dropping work does not drop ownership; a released Space goes to the lowest-load eligible cell, and equal loads defer to the cell admitted first so ties never flap the version; load is the intent-queue fill ratio in percent and readiness is "kernel not frozen"); every accepted registration pushes the full-pool authoritative ownership view, with per-version dedup on the cell side applied into the kernel routing table; expiry release zeroes the owner and re-claiming advances the version as an ABA guard, while an offline former owner converges through ready=0 revocation markers on re-registration — default Spaces refuse revocation, and occupied Spaces enter a bounded pending-revoke table retried every tick until vacated (a World re-claim cancels the stale revoke; the latest view wins), with cell-level scale-down orchestration landed (a World-owned retire intent, beginCellRetire/cancelCellRetire: setting it stops new claims for that cell and returns its assignments to the pool while in-flight activity drains naturally without being aborted, and a miss reports explicitly; cancelling only clears the intent and never reclaims assignments already taken by another cell; a retiring cell is excluded from least-load deferral; the management command face is landed (contract 963/966 cell_retire_request/cell_retire_reply plus a fleetctl retire --cell N [--cancel] subcommand: begin sets the intent and returns assignments to the pool, cancel only clears the intent, the reply synchronously carries explicit miss/invalid codes and the management epoch, and no in-flight drain is waited on — draining converges naturally), while migration orchestration is deferred); control-link grace freeze and old-executor isolation are landed (a control link down beyond the --link-grace-ms window freezes the kernel — simulation paused and the admission gate closed; unfreezing only follows a verified 961 re-admission, and an adjudication rejection (stale-epoch code 3 or contract-compat code 5) freezes the executor on its own; the World-side epoch watermark blocks stale-epoch resurrections after expiry removal — the cross-restart persistent tombstone --world-journal is landed (an append-only journal: accepted advances append a `cell_id
DBApp/DBAppMgr storage dutiesdatabaseLoad/save, storage routing, durable outcomes; no reward-rule decisions.apps/database provides M1 load/save and a file journal. Write generations, storage partitioning, and complete queues remain pending.
Local bwmachined supervisionmachinedStart, stop, supervise, restart local processes; no player Base or Space placement decisions.Reuse supervision; validate readiness and business recovery separately.
Proxy connection/session dutiesgateway plus Base/session associationBigWorld Proxy belongs to Base-side entities. Apollo has a separate gateway socket owner; gateway alone is not a complete Proxy implementation.Connections/partial sessions exist; Base/cell routing incomplete.

These are responsibility mappings, not process renames. cell registers with its owning worldServer, which owns topology placement. loginServer holds World endpoints and player ownership/location projections; directory projections and gateway caches are not second topology writers.

Source boundaries: CellAppMgr, BaseAppMgr, Base, and Proxy.

2. Space and gameplay ​

ConceptBigWorld meaningApollo counterpart/boundary
Map resourcesStatic geometry/resources loaded by runtime spacesSceneDescriptor references assets, not an activity or process.
SpaceAn identified runtime coordinate space spanning one or more CellsCorresponds to the spatial meaning of Apollo's existing Scene. Scene is the current code type name; the execution kernel now has an explicit space→scene routing table (CellApp add_space / scene_id_of_space), so one process can host multiple Spaces, and the mapping is a table rather than an identity alias. Extend logical-space/partition boundaries without stacking synonymous Scene→Space containers.
CellA spatial partition owning authoritative entities within its rangeReuse Space association, partition ID, bounds, host process, and topology version. Not an execution-process name.
CellAppProcess hosting CellsApollo cell execution process, potentially hosting Cells from multiple Spaces.
InstanceNo one-to-one built-in counterpart to Apollo's eight-state gameplay lifecycle was established in the inspected spatial coreRetain existing group, objective, clock, phase, settlement, and cleanup management. It associates with runtime space and is not another Space/Cell name or a claimed native BigWorld type.

Default deployment has one cell execution process and one full-range Cell per Space. Multiple activity Spaces/Cells can share that process. Scale whole Spaces/Cells to additional processes first; future seamless simulation may partition one Space across multiple Cells.

Space, Cell, executor and Instance boundaries: initially one Cell per Space, with multiple Cells in one Space reserved for later.Space, Cell, executor and Instance boundaries: initially one Cell per Space, with multiple Cells in one Space reserved for later.
Target design. Implementation status is documented separately.Open full-size diagram

Instance is gameplay rather than a spatial layer. Temporary tower-defense activities manage their objectives, settlement, and associated Space. Persistent Spaces need no temporary Instance. Two groups can load the same assets into separate runtime Spaces. The existing one-Instance/one-Scene rule is Apollo gameplay scope, not a universal BigWorld constraint.

Space manages Cells and positional lookup; Cell associates bounds/entities with a Space; CellApp hosts execution.

3. Players, visibility, and calls ​

BigWorldApollo counterpartAuthority/implementation boundary
Base entitybase::Avatar and other persistent objects in baseServerBase validates persistent gameplay and saves through database; simulation transfers retain storage affiliation, while Base hosting can migrate independently. base::Avatar is not a complete generic Base-entity implementation.
Cell/Real entityAvatar and simulated Entity in the owning cell partitionOne effective simulation writer per entity. Avatar is a player gameplay type, not another process. Preserve entity IDs through transfer.
Ghost entityReserved non-authoritative adjacent-Cell projectionSupports visibility/queries, not independent damage, rewards, or profile writes. Replication/deduplication/expiry are incomplete; a transfer snapshot is not a persistent Ghost.
WitnessPartial observer-view duties in SceneAoi, ViewerState, and attribute syncView management differs from cross-partition projection. Local AOI is not complete Witness or cross-Cell visibility.
Mailbox/EntityCallRemoteEntityRef, method metadata, RouteResolver, message contractsValidate real addressing/authority/reply wiring; local primitives do not establish distributed calls or old-version decoding.
Proxy/client associationgateway connections, Session, and Base associationConnection, profile, and spatial entity have separate owners; changing simulation hosts need not replace client sockets.

See Cell Entity for Real/Ghost ownership and Witness for observer views. These support comparisons, not claims that Apollo implements them.

Scope of the Avatar name ​

Avatar describes a character, not a Cell execution location. BigWorld's 2.1 glossary also includes NPCs, and its tutorial and KBEngine demos show Base/Cell parts. Apollo maps base::Avatar to the player's Base part and cell::Avatar to the Cell part. This implementation mapping neither makes upstream Avatar Cell-only nor establishes either name as common industry terminology. See player object model for sources, other engines, and naming assessment.

4. Apollo request ownership ​

Apollo process architecture: world is the manager (register/topology/capacity/migration) and cellServer the standalone simulation executor (Scene/Avatar/AOI/battle/Lua), coordinated over 960 register/961 verdict/962 assign/963 retire/967 self-report; Base owns player profiles and base gameplay persisted via database; gateway routes directly to Base and cell; interfaces receives platform callbacks; machined spawns and supervises; logger/admin collect logs and metrics.Apollo process architecture: world is the manager (register/topology/capacity/migration) and cellServer the standalone simulation executor (Scene/Avatar/AOI/battle/Lua), coordinated over 960 register/961 verdict/962 assign/963 retire/967 self-report; Base owns player profiles and base gameplay persisted via database; gateway routes directly to Base and cell; interfaces receives platform callbacks; machined spawns and supervises; logger/admin collect logs and metrics.
Target design. Implementation status is documented separately.Open full-size diagram

Base profile authority and Cell simulation authority concern different data. Cross-server simulation receives gameplay snapshots/state and trusted Base association, not full profiles or storage credentials. Base rollout hands off persistent objects, cell rollout hands off simulation, and worldServer rollout hands off management topology and in-flight transfers.

5. Seamless-world reservation and current scope ​

The initial implementation target is one executor and one Cell per Space. Seamless execution is disabled, but the design expresses multiple Cells per Space; deferral is not a permanent prohibition.

Reserve separate Space/Cell/process identities, global coordinates/stable entity IDs, bounds/adjacency/topology versions, per-entity authority generations, Real/Ghost/view boundaries, complete runtime snapshots, and cross-Cell ordering/adjudication/deduplication/reconciliation. Shared Instance objectives/settlement require one logical owner, not a shared mutable object or global lockstep across all partitions.

Implement spatial splitting, adjacent replication, boundary combat, dynamic load balancing, and takeover when required. Default deployment need not run these algorithms; interfaces must not equate a Space with one process forever.

6. Existing code and migration ​

Apollo codeCorrespondenceMissing integration
WorldApp, World, WorldHostCurrently combine management and simulationSeparate worldServer management from cell execution; existing names identify implementation only.
Scene, SceneDescriptorLocal spatial container and static resource referenceExplicit space→scene routing table landed (space ID and scene ID are separate domains); unified global coordinates and separating local partition state from logical-space identity remain pending.
InstanceTemporary activity lifecycleKeep eight states; add durable remote settlement and exclusive shared-state ownership.
base::Avatar, cell::AvatarPersistent Base object / player Cell entitySeparate hosts, snapshots, trusted associations; remove cross-boundary pointer access.
SceneAoi, ViewerStateLocal partition visibilityAdd adjacency replication, merged spatial visibility, deduplication, continuity.
WorldAssignment, RemoteEntityRefRouting/reference primitivesSeparate Base, World, Space, Cell, and process identities with authority/version checks.
SceneTransferExplicit scene departure/recreationSame-Space Cell handoff preserves health, skills, clocks, and necessary script state without scene-exit reset.

This documentation does not rename C++ types, executables, or wire fields, and does not claim implementation is complete. Root todo.md tracks migration under this single semantic model.

See World and cell management, a review draft covering the proposed short binary name world, default manager role and the standalone cellServer executor entry, local automatic growth, and natural shrinking. Execution kernel extraction and the cellServer standalone entry are now landed (world --role=cell is explicitly rejected; cellServer is the executor entry; see the L104 first slice in the root todo); the explicit Space↔Scene mapping is landed too (L99 first slice — space→scene routing table hosting multiple Spaces per process); both cell registration faces are landed (L101: 960/961 raw frames with an epoch-adjudicating registry, plus --register-host/--cell-id cell-side dialing and re-dial; the contract-compat projection adjudication is landed — 960's compat declaration must equal the World's own projection or it is rejected (mismatch or undeclared) with code 5); heartbeat expiry and stale-entry removal are landed (periodic 960 keep-alive plus the --cell-expiry-ms window, re-registration through the fresh-admission path); the multi-Space declaration wiring is landed (carrying on from the L99 slice — --add-space <id>:<name> wires config-declared Spaces at the startup window, idempotent on duplicates, entry rejects invalid or default-colliding ids); the first World allocation slice is landed (962 cell_space_assign — the --assign-spaces pool is claimed exclusively by the lightest-load eligible cell (unready or draining cells claim nothing new but keep their existing assignments), pushed on every accepted registration, cell-side per-version dedup applies it; capability-bit requirement adjudication is landed (a pool entry may carry <id>[:<needs>], claiming must cover every needs bit, a Space with no eligible candidate is left unassigned, and a deferral target must be eligible too); the L108 recycle slice refines 962 into a full-pool ownership view — expiry release zeroes the owner without touching the version, re-claiming advances it as an ABA guard, and offline former owners converge through ready=0 revocation markers on re-registration; rebalancing strategy/topology versioning follow the L108 later batches); the first control-link grace freeze and old-executor isolation faces are landed (cell-side --link-grace-ms grace freeze plus unfreeze only through a verified 961 re-admission; the World-side epoch watermark blocks stale-epoch resurrections — the persistent tombstone is landed (--world-journal rebuilds watermarks across restarts; the journal v2 A/R/B record family with write-ahead claims and reload-to-terminal-state is landed — see the root todo batch ㊴), and disconnect suspect-marking is landed (a peer link drop sets the registry suspect flag, cleared by verified re-admission); the reconciliation adjudication face is landed (the 967 cell_space_report post-admission self-report, per-item cross-check, and per-Space conflict freeze — see root todo batch ㊵; restart e2e and the persistent-volume lock follow batch C); the cell-level retire management command face is landed (the 963/966 contract pair plus the fleetctl retire subcommand, following the L104 retire orchestration batch — see the root todo). Local automatic growth, natural shrinking, and automatic failover remain pending.

Released under the MIT License