Appearance
API
60 modules from 2026.09.22-r1.
| Module | Require | Summary |
|---|---|---|
sdk.action_broker | sdk.action_broker | @type library Global action broker for coordinating independent scripts. Actions reserve one or more channels atomically, then keep those channels until their acknowledgement arrives (or the action fails/cancels). Network callbacks only enqueue copied evidence; pump() is the sole callback execution point. |
sdk.alert_service | sdk.alert_service | Typed-event/live-snapshot alert service. Native notification is optional; history and callbacks work identically in tests and headless environments. |
sdk.cave_action_graph | sdk.cave_action_graph | Deterministic checkpoint action graph. Documents contain data only: custom behavior is resolved by registered callback name, never by executing strings. |
sdk.combat_rotation | sdk.combat_rotation | @type library Ordered spell/rune combat rotation. Rule selection is deterministic; all execution is deferred through the global action broker and revalidated at send time against live creatures, inventory, tiles, cooldowns and safety. |
sdk.combat_safety | sdk.combat_safety | Fail-closed combat/PvP/AoE safety for shipped high-level bots. Low-level Packet/LocalPlayer methods intentionally remain primitives. |
sdk.combat_shapes | sdk.combat_shapes | Exact affected-tile resolution for player spells, runes and direct attacks. |
sdk.container_service | sdk.container_service | Event-driven open-container lifecycle, indexing, roles, and bounded traversal. Physical identities are stable for one session generation; runtime container ids may be reused by the client and are therefore never exposed as identity. |
sdk.creatures | sdk.creatures | Creature classify + packet cache (skull, party, type, summoner, icons, outfit). Kind matches Game Engine/CreatureCatalog.cpp ClassifyKind, then the live TCreature.kind byte when applyCreatureData has remapped protobuf 0/1/2/5/7 onto compact 0..4 (player/monster/npc/summon-own/summon-other). |
sdk.data | sdk.data | Catalogs. Official client map.dat / staticdata.dat win over Canary. NPCs and towns come from sdk/data/_client_npcs.lua (JSON decode of client/npcs.json). Canary _*.lua is the fallback when the client extract is missing. Spec: docs/superpowers/specs/2026-08-21-sharptibia-data-design.md |
sdk.destinations | sdk.destinations | @type library Semantic destination and multi-hop NPC travel resolver. It converts the generated town/NPC/travel catalog into a small graph; local walking remains the responsibility of sdk.path / sdk.navigator. |
sdk.engine | sdk.engine | High-level reads: local player, creatures, viewport, typed inbound events. Creature rows come from a Lua TCreatureStore walk (live bytes). Native game.get_creatures is a no-session / test fallback — C++ caches that list per Present and the logic thread would otherwise see last frame. Player getters re-read the TCreature* they keep. GetLocalPlayer overlays the local TCreature plus TPlayerData (capacity, xp, ...) from the same walk. |
sdk.equipment_rules | sdk.equipment_rules | Ordered conditional loadout selector. This module only calls loadouts.apply; all actual mutations remain in the brokered equipment-loadout module. |
sdk.farm_planner | sdk.farm_planner | @type library Versioned farming-plan runtime. The browser/backend owns immutable plan documents; this module validates and maps the latest downloaded document onto the proven farming modules, derives the active hierarchical task, enforces hunt polygons, applies stop conditions, and publishes compact status. |
sdk.healing_service | sdk.healing_service | @type library Self-only healing/support policy service. Rules decide what should happen; the global action broker decides when it may happen alongside other scripts. |
sdk.hunt_analytics | sdk.hunt_analytics | @type library Authoritative hunt/session analytics. The service consumes typed protocol events and (optionally) terminal action-broker snapshots. It never parses chat text and never sends telemetry over the network. |
sdk.input | sdk.input | Official tibia::input::TGameAction catalog + publish. Resolve by name (ToggleMounted, TGameActionUse). Do not paste RVAs. Simple actions publish through TGameClient signal 0. Parameterized Use/Look/MoveObject stay on sdk.packet / sdk.tools until a factory is wired. |
sdk.intent_arbiter | sdk.intent_arbiter | @type library Deterministic action-channel arbiter used by the farming planner. Intents are plain tables and may reserve one or more channels. The arbiter adds bounded urgency/risk/waiting bonuses to the base priority so low-priority work eventually runs without allowing it to overtake emergencies. |
sdk.inventory | sdk.inventory | Live backpack / equipped / depot / stash stacks from TContainerStorage. Gold sums gold coin (3031), platinum (3035), crystal (3043). Depot and stash return "not open" when those windows are closed. |
sdk.keys | sdk.keys | Win32 virtual-key names and Ctrl/Alt/Shift combos for game.input_snapshot and game.on("key_down"). Not TGameAction (that is sdk.input) and not overlay UI keys. |
sdk.kite | sdk.kite | Maximin pack goal + Path.to. Does not walk or attack. Ranger: pick a reachable tile that maximizes min Chebyshev to the pack while staying in [min_range, attack_range] when possible. In-range steps try north/south/east/west first. Diagonals only when every cardinal neighbor is blocked (same two-pass as Path.to). Spec: docs/superpowers/specs/2026-08-21-sdk-kite-design.md |
sdk.localplayer | sdk.localplayer | Local character: Player reads plus talk / walk / use / attack. Actions return ok, err. |
sdk.lure | sdk.lure | Pack-pull decision. Does not walk or attack. CaveBot and farm_planner consume the phase; Path / fight stay elsewhere. |
sdk.market | sdk.market | Outbound market packets. Nested MarketOfferID lives here; AppearanceTypeUpgradeable stays on the packet builder because other domains reuse it. |
sdk.math | sdk.math | Tile-grid position helpers. Chebyshev is the default distance (Tibia walk/attack range). Direction numbers match Canary/TFS: N=0 E=1 S=2 W=3 SW=4 SE=5 NW=6 NE=7 None=8. Spec: docs/superpowers/specs/2026-08-21-sdk-position-design.md |
sdk.mem | sdk.mem | Low-level conversion, pointer, alloc, layout, std::map walk, appearance, session, queue, string, RTTI, and hex helpers. For SDK internals and typed-event fallbacks. Application scripts start at sdk.engine. |
sdk.monster_telemetry | sdk.monster_telemetry | @type library Passive, bounded monster telemetry. This module never issues game actions. Creature snapshots provide movement/health observations; KillTracking is the authoritative kill source. Classification is descriptive and includes an explicit confidence instead of presenting learned behavior as fact. |
sdk.movement | sdk.movement | Thin wrappers around native game.walk / game.move_to. Directional steps are official one-shot TGameActionPlayerMovementIntent actions; bounded town recovery segments use MoveTo so the client keeps normal pre-walk cadence. Rotate / turn is the facing packet fallback when game.rotate is missing. |
sdk.navigator | sdk.navigator | Stateful one-tile movement controller. Prevents walk queue flooding, remembers temporarily blocked tiles, and suppresses immediate direction reversals that cause left/right oscillation. |
sdk.npc | sdk.npc | NPC greet / say / trade / buy / sell. nearest() walks TCreatureStore and accepts only positively typed or catalog-confirmed NPCs. bank / travel pick a clerk or boat/carpet by catalog, then greet + NPC talk (mode 12). Server-side range, open trade window, and capacity still apply. |
sdk.packet | sdk.packet | Packet builder: catalog lookup, nested protocol objects, and enqueue. Resolve by name (TalkMessage / GameclientMessageTalk), never by RVA. Nested objects (ObjectPosition, ObjectIdentifier) are not packets; write their live vtable the same way. Unique GameclientMessage* sends live on the owning module (Inventory, Npc, Talk, Market, LocalPlayer, Movement). Do not hard-code catalog counts: the IDA-generated inbound table is refreshed whenever the client protocol moves. |
sdk.party_assist | sdk.party_assist | @type library Party following and optional friend healing without using client follow. Movement and healing use disjoint broker channels so target combat continues. |
sdk.path | sdk.path | A* on Data.map.walkable / game.map.find_path. Cross-floor uses stairs and teleports from world.bin. Does not walk or attack. avoid_unpass tries native find_path first, then probes the path for live unpass. Long solves belong on plan_path (MapService worker), not this tick. Two-pass: 4-way first; 8-way squeeze only when no cardinal path exists. Live creatures do not block. Default Chebyshev cap is 128. Spec: docs/superpowers/specs/2026-09-02-cardinal-first-path-design.md |
sdk.player | sdk.player | Creature wrapper. TCreature fields (hp, pos, speed, skull, party, kind, …) re-read the live pointer when one exists. Fixture tables without ptr keep the values they were constructed with. Actions live on LocalPlayer. |
sdk.profile | sdk.profile | Per-character key/value store on game.storage, plus alarm predicates. Alarms log/callback as before and use the optional native alert sink. |
sdk.resources | sdk.resources | Session ResourceBalance cache keyed by official type. Bank / inventory gold / prey / hunting / dust arrive when those windows update; last-write-wins per type, not per event name. Canary Resource_t is intent for the type field (not a packet opcode). |
sdk.rule_engine | sdk.rule_engine | @type library Generic deterministic rule selection with explicit cooldown ownership. Rules are ordered by descending priority, ascending explicit order, and then insertion order. Selection never marks a cooldown; callers retain control of side effects by calling mark() only after the chosen action was accepted. |
sdk.schedule | sdk.schedule | Timers on game.on("tick"). after / every are non-blocking. wait(ms) yields only when the caller is a coroutine. |
sdk.session | sdk.session | Credential-free session recovery. The native layer invokes Tibia's official retained-credential reconnect slot. This module adds an opt-in retry policy; it never accepts account, password, authenticator, session-key, character, or packet parameters. |
sdk.shop_qty | sdk.shop_qty | NPC shop amounts. One formula for recover, commerce, and the action graph. Buy is remaining-to-target. A cached count must be recomputed against have immediately before the packet; never send target-have from a stale snapshot. |
sdk.skills | sdk.skills | Live skill levels from TPlayerSkillStats. use() speaks the words through Talk.talk (mode 1). |
sdk.status | sdk.status | Live self-status cache: conditions, server target, tactics, last vitals, plus login account facts (premium / blessings) that survive WorldEntered. Filled from inbound PlayerState (162), UpdateTarget (163), SetTactics (167), PlayerDataCurrent (160), PlayerDataBasic (159), Blessings (156). Official protobuf assign: PlayerState has_bits bit0=state u64@24, bit1=icons u32@32. |
sdk.storage | sdk.storage | Live depot discovery and deterministic depot-box operations. A route checkpoint is the search anchor; the locker itself is selected from the current viewport so plans do not depend on one city's appearance id. |
sdk.talk | sdk.talk | Outbound TalkMessage (type 150). mode 1=say, 2=whisper, 5=private-to, 12=NPC. |
sdk.tile | sdk.tile | Unified static/live tile view. Reads only; actions belong to tools/path APIs. |
sdk.tiles | sdk.tiles | Live items from Tibia's RTTI-identified TWorldMapStorage. Map events mark the cache dirty; the next reader obtains one coherent current snapshot. game.map is static terrain. This module is the live ordered object stack. |
sdk.tools | sdk.tools | Rope, shovel, machete, door, loot, move, equip, close. Prefer official TGameAction* / handler publish (Use / Open / MoveObject / TryToEquip / QuickLoot). Packet enqueue stays only when the live handler or RTTI is missing. |
sdk.transitions | sdk.transitions | Automatic entrances for pathing. Interactive blockers are discovered from Tibia's live map stack and approached by the caller; request() performs one brokered use and verifies the resulting teleport/open state. |
sdk.world_navigation | sdk.world_navigation | Asynchronous multi-floor route planner. Heavy WorldGrid A* runs on the MapService worker; the game thread executes only a small semantic action graph made of bounded walking legs and verified transition actions. CaveActionGraph is deliberately resolved lazily: callers which inject a scoped factory and broker must never fall through to the process-global graph/broker pair. |
sdk.world_objects | sdk.world_objects | Semantic fixed/dynamic map objects from the live TWorldMapStorage stack. Classification calls Data.interaction, which reads official TAppearanceType flags (lens-help / unpass) and Canary interaction metadata. Display names are never used as a classifier. |
sdk.zoom | sdk.zoom | Official world-map camera scaling for the current client. IDA confirms that TGameSessionBase owns shared_ptr<TWorldMapCamera> at session+0xC8 and that the official float setter rebuilds both QMatrix4x4 instances and emits the viewport-change signal. The server viewport remains the constructor-default 18x14 rectangle (15x11 playable plus margins). |
game | — | — |
game.dbg | — | Research/fallback kernel. Prefer sdk.packet and named catalog rows. Do not paste RVAs or live addresses into shared scripts. |
game.overlay | — | — |
game.log | — | — |
game.map | — | Native map reads return nil plus an error while loading/off-thread. A false walkability value is authoritative only after ready() succeeds. |
game.http | — | HTTP is asynchronous. poll(id) returns nil with no error while pending, nil, error for an unknown id, or one terminal response and then removes it. |
game.alert | — | — |
game.storage | — | Per-script storage. Names are 1..80 ASCII letters/digits/_/-/. and must not be . or ... Payloads are limited to 2 MiB. |
game.session | — | Low-level native session facade. reconnect accepts no arguments and reuses only state retained inside the official client. true, status means queued locally; confirm completion through WorldEntered or state().in_world. |
game.planner | — | — |