turret.move

  <a href="https://github.com/evefrontier/world-contracts/pull/95">
    PR #95</a>

on <code>world-contracts</code>.
It has not been merged to <code>main</code> and may change before release.
<br/>The Turret API and architecture are subject to significant changes before the official release.

The Turret is a programmable defense structure in the EVE Frontier world. It is a Sui shared object anchored to a Network Node, projecting offensive or defensive power over a fixed location based on builder-defined targeting rules.

Builders control two key behaviors:

• InProximity — reacts to ships entering the turret’s engagement range.
• Aggression — responds to hostile actions from ships within range.

A configurable on-chain priority queue determines how targets are ranked and engaged. Owners can define custom targeting logic through extension contracts using the typed witness pattern.

Architecture

The implementation composes several Layer 1 primitives and supports custom targeting logic through the typed witness extension pattern.

flowchart TD
    subgraph Turret Assembly
        T[Turret Object]
    end

    subgraph Primitives
        Status["status.move"]
        Location["location.move"]
        Energy["energy.move"]
        Metadata["metadata.move"]
    end

    subgraph Targeting
        P["Priority Queue (BCS)"]
        Rules["Default Rules"]
        Ext["Custom Extension"]
    end

    subgraph Infrastructure
        NWN["Network Node"]
        Receipt["OnlineReceipt (hot potato)"]
    end

    T --> Status
    T --> Location
    T --> Energy
    T --> Metadata
    T -->|energy_source_id| NWN
    T --> P
    Rules -->|apply_target_priority_rules| P
    Ext -.->|typed witness| T
    Receipt -.->|verify_online| T

Key Concepts

• Two Behaviors — The game invokes turret logic through two triggers: InProximity (a new ship enters range) and Aggression (a hostile action occurs on-grid). Both call get_target_priority_list to update the targeting queue.
• Priority Queue — Targets are ranked in a vector<TurretTarget> serialized as BCS bytes. The function get_target_priority_list receives the current list plus a new target and returns the updated list.
• Default Targeting Rules — When no extension is configured, the built-in apply_target_priority_rules function applies: aggressors are always added; non-aggressive targets from a different tribe than the owner are added; same-tribe non-aggressors are ignored.
• Energy Dependency — Turrets must be anchored to a Network Node and consume energy from it to remain online.
• Extension Pattern — Uses authorize_extension<Auth> to register a typed witness, allowing builders to inject custom targeting priority logic. When an extension is configured, the game resolves the extension package and calls get_target_priority_list in that package instead.
• OnlineReceipt (Hot Potato) — Calling verify_online returns a non-storable OnlineReceipt proving the turret is active. The default get_target_priority_list consumes it internally; extensions must call destroy_online_receipt(receipt, auth_witness) to destroy it.

Data Structures

Turret

The core shared object representing the turret assembly.

TurretTarget

Represents a potential target in the turret’s proximity. Serialized via BCS for on-chain priority list management.

OnlineReceipt

A hot potato (non-storable, non-droppable struct) returned by verify_online. It proves the turret was online at call time and must be consumed before the transaction ends.

Turret Specializations

Different turret types are specialized against specific ship classes via target_group_id:

These group IDs can be used in extension logic to prioritize targets or lower their priority based on the turret’s specialization.

Error Codes

Events

Core Functions

Owner Functions

These require a valid OwnerCap<Turret> borrowed from the owner’s Character.

• authorize_extension<Auth> — Registers (or replaces) a custom extension witness type on the turret. Once set, the game routes get_target_priority_list calls to the extension package.
• online — Brings the turret online, reserving energy from its connected Network Node.
• offline — Takes the turret offline and releases its energy reservation.

Targeting Functions

• verify_online — Returns an OnlineReceipt (hot potato) proving the turret is online. Aborts with ENotOnline if offline.
• get_target_priority_list — The default targeting entry point. Accepts the turret, owner character, current priority list (BCS bytes), new target (BCS bytes), and an OnlineReceipt. Applies default rules and returns the updated list. Aborts with EExtensionConfigured if an extension is registered (the game should call the extension’s function instead).
• destroy_online_receipt<Auth> — Consumes an OnlineReceipt using a typed witness. Used by extension contracts after custom targeting logic.
• unpack_priority_list — Deserializes vector<TurretTarget> from BCS bytes.
• peel_turret_target — Deserializes a single TurretTarget from BCS bytes.

Network Node Integration (Hot Potato)

These functions handle the hot-potato patterns used when Network Node state changes affect connected turrets.

• update_energy_source_connected_turret — Processes the UpdateEnergySources hot potato when a turret is connected to a new network node via connect_assemblies.
• offline_connected_turret — Processes the OfflineAssemblies hot potato when a network node is brought offline, taking connected turrets offline.
• offline_orphaned_turret — Processes the HandleOrphanedAssemblies hot potato when a network node is unanchored, taking connected turrets offline and clearing their energy source.

Admin Functions

These require AdminACL sponsor verification.

• anchor — Creates a new Turret, connects it to a Network Node, creates an OwnerCap<Turret>, and emits TurretCreatedEvent. Returns the Turret object (must be shared via share_turret).
• share_turret — Converts the turret into a Sui shared object.
• update_energy_source — Reconnects an offline turret to a different Network Node (e.g., after the original was destroyed).
• unanchor — Destroys a turret, releases energy, disconnects from its network node, and cleans up all composed primitives.
• unanchor_orphan — Destroys an orphaned turret (no energy source). Asserts the turret is offline and has no energy source.

View Functions

TurretTarget field accessors: target_id, target_type_id, target_group_id, target_character_id, target_character_tribe, hp_ratio, shield_ratio, armor_ratio, is_agressor, weight.

OnlineReceipt accessor: turret_id.

Default Targeting Rules

When no extension is configured, apply_target_priority_rules applies these rules to each new target:

flowchart TD
    A[New Target] --> B{is_agressor?}
    B -->|Yes| C[Add to priority list]
    B -->|No| D{Same tribe as owner?}
    D -->|No| C
    D -->|Yes| E[Ignore target]

1. Aggressors — Any target flagged as is_agressor (attacking something on-grid) is always added.
2. Different Tribe — Non-aggressive targets from a different tribe than the turret owner are added.
3. Same Tribe — Non-aggressive same-tribe targets are ignored.

Lifecycle Example

sequenceDiagram
    participant Admin
    participant NWN as Network Node
    participant Turret
    participant Owner
    participant Game

    Admin->>Turret: anchor(registry, nwn, character, ...)
    Admin->>Turret: share_turret()
    Owner->>NWN: deposit fuel & online
    Owner->>Turret: online(nwn, energy_config, owner_cap)
    Game->>Turret: verify_online() → OnlineReceipt
    Game->>Turret: get_target_priority_list(turret, character, list, target, receipt)
    Turret-->>Game: updated priority list (BCS bytes)
    Owner->>Turret: offline(nwn, energy_config, owner_cap)
    Admin->>Turret: unanchor(nwn, energy_config)

Related Documentation

• Assembly Framework — Base assembly lifecycle
• Network Node — Providing energy to turrets
• Extension Examples — Examples of custom logic, including Turret Extension
• Smart Assemblies Overview — High-level guide to programmable assemblies
• Ownership Model — Borrow-use-return pattern for OwnerCap
• Status Primitive — Assembly status lifecycle
• Location Primitive — Spatial coordinate management
• Energy Primitive — Energy reservation and release