Game API
2026-10-04 audit: this page was rewritten against the actual state of HEAD. After P1-3 the repo's only AOI implementation is
SceneAoi;ECSWorld/ECSSystemdo not exist (ECS convergence comes with P2); attributes follow theAttributeContainer/AttributeManagercontainer model (modifier computation not implemented).
apollo::game::core::EntityId / PlayerId
namespace apollo::game::core {
class EntityId {
public:
constexpr EntityId();
constexpr explicit EntityId(uint64_t id);
constexpr uint64_t value() const;
constexpr bool is_valid() const;
static constexpr EntityId invalid();
};
// strongly-typed player ID (P0-2): same shape as EntityId but no implicit
// conversion between them — PlayerId identifies the long-lived player object
// (the base::Avatar domain), EntityId identifies in-scene entities
class PlayerId {
public:
constexpr explicit PlayerId(uint64_t id);
constexpr uint64_t value() const;
constexpr bool is_valid() const;
};
}apollo::game::core::Entity
namespace apollo::game::core {
class IEntity {
public:
virtual ~IEntity() = default;
virtual EntityId get_id() const = 0;
virtual std::string get_type() const = 0;
virtual void on_spawn() {}
virtual void on_despawn() {}
virtual void on_update(float delta_time) {}
};
class Entity : public IEntity {
public:
explicit Entity(EntityId id, std::string type = "Entity");
EntityId get_id() const override;
std::string get_type() const override;
void on_spawn() override;
void on_despawn() override;
void on_update(float delta_time) override;
// components (IEntityComponent: get_type_name + on_attach/on_detach/on_update)
template <typename T>
std::shared_ptr<T> add_component();
void add_component(ComponentPtr component);
void remove_component(const std::string& component_type);
template <typename T>
std::shared_ptr<T> get_component() const;
};
}Thread safety: unsafe (must be called on the same thread — scene-thread single writer)
apollo::game::world::SceneAoi
After the P1-3 convergence, the repo's only AOI implementation: the 3x3 grid, owned by one Scene, isolated per scene, decoupled from entity type (it only knows EntityId + position values).
namespace apollo::game::world {
class SceneAoi {
public:
struct Vec3 { float x = 0.0f; float y = 0.0f; float z = 0.0f; };
struct Event {
enum class Kind : std::uint8_t { Enter = 0, Sync, Leave };
Kind kind = Kind::Enter;
apollo::game::core::EntityId observer{}; // who the event goes to
apollo::game::core::EntityId subject{}; // who it is about
};
using EventSink = std::function<void(const Event&)>;
void set_event_sink(EventSink sink); // silent by default
SceneAoi(); // 1x1 degenerate grid
SceneAoi(float width, float height, float grid_size, float view_radius);
// set maintenance (maintenance dispatches: Enter/Sync/Leave)
void enter(apollo::game::core::EntityId id, const Vec3& position);
void move(apollo::game::core::EntityId id, const Vec3& new_position);
void leave(apollo::game::core::EntityId id);
// queries (3x3 grid + radius filtering; viewers_of includes self)
std::vector<apollo::game::core::EntityId> viewers_of(apollo::game::core::EntityId id) const;
std::vector<apollo::game::core::EntityId> viewers_at(const Vec3& position) const;
bool contains(apollo::game::core::EntityId id) const noexcept;
std::size_t entity_count() const noexcept;
};
}Thread safety: unsafe (belongs to the scene thread — single writer, no internal locks)
apollo::game::world::ViewerState
Per-observer view watermark, the set-difference baseline for AOI event dispatch (the authoritative ledger of "who sees what").
namespace apollo::game::world {
class ViewerState {
public:
void reset(apollo::game::core::EntityId observer); // register (re-register resets to empty)
void drop(apollo::game::core::EntityId observer); // unregister
bool tracked(apollo::game::core::EntityId observer) const noexcept;
bool visible(apollo::game::core::EntityId observer,
apollo::game::core::EntityId subject) const noexcept;
std::vector<apollo::game::core::EntityId> visible_set(
apollo::game::core::EntityId observer) const;
bool add(apollo::game::core::EntityId observer,
apollo::game::core::EntityId subject); // true = newly visible (ENTER)
bool remove(apollo::game::core::EntityId observer,
apollo::game::core::EntityId subject); // true = left view (LEAVE)
std::vector<apollo::game::core::EntityId> remove_everywhere(
apollo::game::core::EntityId subject);
std::size_t size() const noexcept;
};
}apollo::game::battle::BattleSystem (skeleton)
ECS convergence comes with P2-1/P2-2; the current state is an in-scene skeleton of entity-set registration + tick updates.
namespace apollo::game::battle {
class BattleSystem {
public:
BattleSystem();
void update(float delta_time);
void add_entity(EntityPtr entity);
void remove_entity(apollo::game::core::EntityId id);
size_t get_entity_count() const;
};
}apollo::AttributeContainer (attribute container)
Header include/apollo/game/attributes/attribute.hpp. AttributeValue is a std::variant<int32_t, int64_t, float, double, bool, std::string>.
namespace apollo {
class AttributeContainer {
public:
explicit AttributeContainer(uint64_t objectId);
bool SetAttribute(uint32_t attributeId, const AttributeValue& value);
bool GetAttribute(uint32_t attributeId, AttributeValue& value) const;
template<typename T>
T GetAttribute(uint32_t attributeId, const T& defaultValue = T{}) const;
bool AddAttribute(uint32_t attributeId, const AttributeValue& delta);
void SetAttributes(const std::vector<std::pair<uint32_t, AttributeValue>>& attrs);
const std::unordered_map<uint32_t, AttributeValue>& GetAllAttributes() const;
void Clear();
void SetChangeListener(std::function<void(const AttributeChangeEvent&)> listener);
private:
mutable std::mutex mutex_; // internal mutual exclusion
};
}apollo::AttributeManager (attribute definition registry)
namespace apollo {
class AttributeManager {
public:
static AttributeManager& Instance();
bool RegisterAttribute(const AttributeDef& def);
const AttributeDef* GetAttributeDef(uint32_t attributeId) const;
const std::unordered_map<uint32_t, AttributeDef>& GetAllAttributes() const;
std::shared_ptr<AttributeContainer> CreateContainer(uint64_t objectId);
std::shared_ptr<AttributeContainer> GetContainer(uint64_t objectId);
void DestroyContainer(uint64_t objectId);
bool LoadFromConfig(const std::string& configFile);
private:
AttributeManager() = default; // singleton
mutable std::mutex mutex_;
};
}AttributeDef (attribute definition): id/name/type (value-type enum INT32..STRING)/defaultValue/minValue/maxValue/persistent/syncToClient. AttributeChangeEvent: objectId/attributeId/oldValue/newValue.
Sessions and Directory (session sublibrary, G-1 deliverable surface)
Nine headers under modules/game/session/ — cross-process session/fleet machinery (the G-1 fleet-discovery closing batch + P1-5 recovery); API details are in the headers and design docs:
PlayerDirectory— online directory (epoch/suspend windows/mirrored-entry projection, re-report convergence; EventSink reports session_up/down/moved/kicked).DirectoryPublisher— cross-process directory mirroring (the "APD2" wire: Delta/SnapshotRequest/SnapshotReply/FullReport, owner-side snapshot publishing).FleetRecoveryCoordinator— recovery phase made cross-process (Normal↔Recovering, converges on open admission).RecoveryCoordinator— in-process recovery orchestration (journal replay → Avatar restore → admission gate, restore-not-kick).AvatarManager/base::Avatar— the long-lived player-state authority (AvatarState machine, single-writer discipline);AvatarRewardSink— battle settlement rewards → base::Avatar accounting.SessionLocator/WorldAssignment— session location and world assignment arbitration.
World and Instances (remaining world-sublibrary pieces)
Scene(SceneTickPhase state) — the scene runtime boundary (AOI ownership, judgment domain);SceneDescriptor/SceneTransferRequest— scene description and the five-step scene transfer.Instance— instances as first-class citizens (eight-state one-way machine Create→…→Destroyed).World/WorldSession(WorldSessionState)/WorldSessionManager— the world runtime and session management.Avatar(AvatarState) — the player avatar state.
Battle runtime (battle_runtime / battle_replay)
BattleRuntime(BattlePhase state machine) — the deterministic battle domain (logic tick axis only, no wall clock; RNG substream per the battle-determinism contract).BattleReplay(ReplayTuple) — the replay surface (four-tuple: binary_id / world_seed / snapshot_pos / inputs; header + free functions, not a class).
Social (social sublibrary)
Party / Guild — the party and guild foundations (the party surface is a session-scoped container, no cross-process sync — cross-server semantics wait on the decision chain).
Not implemented: attribute modifier computation (addModifier/AttributeModifier).
apollo::game::attrsync (attribute delta sync)
The per-viewer delta pipeline (attribute-sync §3.1/§3.2/§3.3/§4.1/§5/§7.1/§8.2), delivered in seven batches:
namespace apollo::game::attrsync {
// sequenced change ring log (one per entity)
struct HistoryEntry {
std::uint64_t seq = 0;
std::uint32_t attr_id = 0;
std::int64_t value = 0; // zigzag-encoded value
};
class ChangeHistory {
public:
explicit ChangeHistory(std::size_t capacity = 1024);
std::uint64_t append(std::uint32_t attr_id, std::int64_t value);
std::vector<HistoryEntry> entries_since(std::uint64_t since_seq) const;
std::uint64_t world_seq() const noexcept;
std::size_t capacity() const noexcept;
std::size_t size() const noexcept;
bool wrapped() const noexcept;
};
// per-viewer acked_seq watermark
class ViewerAttrState {
public:
void set_acked(std::uint64_t entity_id, std::uint64_t seq);
std::uint64_t acked_seq(std::uint64_t entity_id) const;
void remove(std::uint64_t entity_id);
std::size_t size() const noexcept;
bool tracked(std::uint64_t entity_id) const; // added in batch 2
};
// varint/zigzag encoding
struct AttrDelta {
std::uint32_t attr_id = 0;
std::int64_t value = 0;
std::uint32_t change_n = 0;
std::vector<std::uint8_t> encode() const;
static std::optional<AttrDelta> decode(const std::vector<std::uint8_t>& data);
// batch 3 fix: decode_into returns consumed byte count (not absolute offset)
static std::optional<std::size_t> decode_into(const std::vector<std::uint8_t>& data,
std::size_t offset, AttrDelta& out);
};
// delta assembly + snapshot switching
struct AttrSyncFrame {
std::uint64_t entity_id = 0;
std::uint64_t base_seq = 0;
std::vector<AttrDelta> deltas;
bool is_snapshot = false;
std::uint32_t epoch = 0;
};
class DeltaBuilder {
public:
// snapshot path: deltas carry full current values, base_seq pushed to world_seq (batch 8)
// both paths prune by viewer domain (batch 9, §2.2)
using GroupGate = std::function<bool(std::uint64_t viewer,
std::uint64_t entity, AttrDomain domain)>;
AttrSyncFrame build(std::uint64_t entity_id, std::uint64_t viewer_id,
const EntityAttrs& attrs,
const ViewerAttrState& viewer) const;
void set_delta_attr_threshold(std::uint32_t threshold);
void set_group_gate(GroupGate gate);
};
// batch 9: attribute visibility domains (§2.2)
enum class AttrDomain : std::uint8_t {
kPublic = 0, // AOI domain (default)
kSelf, // owner only (viewer == entity)
kTeam, // owner + same team (via group gate)
kGuild, // guild members (via group gate)
kWorld, // whole-server broadcast (mechanism layer treats as public)
};
// batch 2: per-entity attribute storage
class EntityAttrs {
public:
explicit EntityAttrs(std::uint64_t entity_id, std::size_t history_capacity = 1024);
void set(std::uint32_t attr_id, std::int64_t value);
std::int64_t get(std::uint32_t attr_id) const;
void set_all(const std::vector<std::pair<std::uint32_t, std::int64_t>>& attrs);
bool is_dirty(std::uint32_t attr_id) const;
void clear_dirty();
std::size_t dirty_count() const;
const ChangeHistory& history() const noexcept;
// full current values (for snapshot payload assembly, batch 8)
const std::unordered_map<std::uint32_t, std::int64_t>& values() const noexcept;
// batch 9: attribute visibility domain (undeclared = kPublic)
void set_domain(std::uint32_t attr_id, AttrDomain domain);
AttrDomain domain(std::uint32_t attr_id) const;
std::uint64_t entity_id() const noexcept;
};
// batch 2: pipeline integration layer (AOI wiring + broadcast collect + ACK)
// batch 4: ACK timeout degradation (silent_ticks + is_degraded)
// batch 6: peek read-only precheck
// batch 7: ChangeSink post-write log entry point
class AttrSyncManager {
public:
void register_entity(std::uint64_t entity_id);
bool has_entity(std::uint64_t entity_id) const;
void set_attribute(std::uint64_t entity_id, std::uint32_t attr_id, std::int64_t value);
std::int64_t get_attribute(std::uint64_t entity_id, std::uint32_t attr_id) const;
void on_viewer_enter(std::uint64_t viewer, std::uint64_t entity_id);
std::vector<AttrSyncFrame> on_viewer_enter_collect(std::uint64_t viewer, std::uint64_t entity_id);
void on_viewer_leave(std::uint64_t viewer, std::uint64_t entity_id);
bool has_viewer(std::uint64_t viewer, std::uint64_t entity_id) const;
std::vector<AttrSyncFrame> collect(std::uint64_t viewer, std::uint64_t entity_id);
// batch 6: read-only collection (does not advance acked, does not clear dirty),
// for scheduler prechecks
std::vector<AttrSyncFrame> peek(std::uint64_t viewer, std::uint64_t entity_id);
void ack(std::uint64_t viewer, std::uint64_t entity_id, std::uint64_t seq);
void set_ack_timeout_ticks(std::uint64_t ticks); // batch 4
bool is_degraded(std::uint64_t viewer, std::uint64_t entity_id) const; // batch 4
const EntityAttrs& entity_attrs(std::uint64_t entity_id) const;
// batch 9: domain projection (§2.2; undeclared domain = kPublic)
void set_attr_domain(std::uint64_t entity_id, std::uint32_t attr_id, AttrDomain domain);
void set_group_gate(DeltaBuilder::GroupGate gate); // team/guild membership test
// batch 7: §8.2 post-write log entry point (fires after set_attribute succeeds)
using ChangeSink = std::function<void(std::uint64_t entity_id,
std::uint32_t attr_id,
std::int64_t value)>;
void set_change_sink(ChangeSink sink);
void clear_change_sink();
};
// batch 3: frame codec
std::vector<std::uint8_t> encode_frame(const AttrSyncFrame& frame);
std::optional<AttrSyncFrame> decode_frame(const std::vector<std::uint8_t>& data);
std::vector<std::uint8_t> encode_batch(const std::vector<AttrSyncFrame>& frames);
std::optional<std::vector<AttrSyncFrame>> decode_batch(const std::vector<std::uint8_t>& data);
// batch 6: §5 priority and throttling scheduler
class AttrSyncScheduler {
public:
explicit AttrSyncScheduler(AttrSyncManager& mgr);
// §5.1 bandwidth budget: per-tick byte cap (default 3276 = 32KB/s @ 10Hz)
void set_bandwidth_budget(std::uint64_t bytes_per_tick);
// §5.2 entity importance: 0-255 (contract field importance(class))
void set_entity_importance(std::uint64_t entity_id, std::uint8_t importance);
// §5.3 min_interval: tick count; 0=INSTANT (no throttling)
void set_min_interval(std::uint64_t entity_id, std::uint32_t min_interval);
// §5.2 starvation protection: force send after this many deferred ticks (default 100)
void set_max_defer_ticks(std::uint64_t ticks);
// tick advance: increments the current tick + resets per-viewer budget
void advance_tick();
// scheduling: given a viewer and the visible entity set, returns the
// frames to send this tick (priority-ordered, total encoded size within budget)
[[nodiscard]] std::vector<AttrSyncFrame> schedule(
std::uint64_t viewer, const std::vector<std::uint64_t>& visible);
[[nodiscard]] std::uint64_t current_tick() const noexcept;
[[nodiscard]] std::uint64_t budget_remaining(std::uint64_t viewer) const;
};
// batch 6: peek read-only collection (does not advance acked, does not clear dirty)
// added on AttrSyncManager:
// std::vector<AttrSyncFrame> peek(viewer, entity_id);
} // namespace apollo::game::attrsyncScene × AttrSync wiring (batch 5)
The AOI event consumer lives on Scene (attribute-sync §4.1):
namespace apollo::game::world {
class Scene {
public:
// attach: back-registers existing entities/avatars + takes over the SceneAoi event sink
void attach_attrsync(apollo::game::attrsync::AttrSyncManager& mgr);
// clears the sink + drops the reference (attrsync_ = nullptr)
void detach_attrsync();
[[nodiscard]] bool attrsync_attached() const noexcept;
// takes away the snapshot frames accumulated over the first-sight period
// (accumulation restarts afterwards)
[[nodiscard]] std::vector<apollo::game::attrsync::AttrSyncFrame>
drain_attrsync_frames();
};
}Semantics: Enter/Sync on first sight (the manager has no (observer, subject) viewer state for it) → build ViewerState + a snapshot frame; in-view cross-cell Sync triggers no protocol; Leave → reclaim the ViewerState. In enter(), attrsync registration happens before aoi_.enter() (the newcomer's own snapshot frame requires the subject to be registered already). After attach, spawn_entity/enter register the entity id immediately.
Thread safety: unsafe (scene-thread single writer; the sink captures this, and Scene is not copied — World holds it by unique_ptr)
Boundaries: the client send path and slice compound types are later batches.
