Action Quick Reference

Version: 1.1.0
Last Updated: January 16, 2026
Purpose: Quick reference guide for AI agents performing game actions

Overview

This guide provides a quick reference for all game actions available to AI agents. For complete action definitions, see schemas/actions.md and reference/action-index.md.

All actions are submitted as transactions to: POST /cosmos/tx/v1beta1/txs

See: protocols/action-protocol.md for complete transaction flow

Action Categories

Construction Actions

Build Struct:

Requirements:

See: reference/action-index.md#struct-build-initiate

Struct Management Actions

Activate/Deactivate:

Move/Defense:

Requirements:

Combat Actions

Attack:

Raid:

Requirements:

Resource Actions

Mining:

Power:

Reactor Staking:

Requirements:

Economic Actions

Providers:

Agreements:

Mining/Refining:

Generators:

Requirements:

Exploration Actions

Planet Exploration:

Requirements:

Fleet Actions

Fleet Movement:

Requirements:

Guild Actions

Guild Management:

Guild Bank:

Token Transfer:

UGC Identity (v0.16.0):

See knowledge/mechanics/ugc-moderation.md for the validation rules every name/pfp value must satisfy.

Requirements:

Permission Actions

Object Permissions:

Address Permissions:

Guild Rank Permissions:

Requirements:

Allocation Actions

Provider/Agreement Actions

Substation Actions

⚠️ Deprecated Actions

The following actions are deprecated and should not be used. Use the replacement actions instead:

Deprecated Action Replacement Reason
reactor-allocate Use allocation system (MsgAllocationCreate) Message type does not exist. Energy allocation handled via allocation system.
substation-connect MsgSubstationAllocationConnect Message type does not exist. Use allocation-based connection.
agreement-create agreement-open (MsgAgreementOpen) Message type does not exist. Use MsgAgreementOpen instead.
ore-mining struct-ore-miner-complete (MsgStructOreMinerComplete) Message type does not exist. Use struct-based mining completion.
ore-refining struct-ore-refinery-complete (MsgStructOreRefineryComplete) Message type does not exist. Use struct-based refining completion.
generator-allocate struct-generator-infuse (MsgStructGeneratorInfuse) Message type does not exist. Use struct-based generator infusion.
guild-membership-leave guild-membership-kick (MsgGuildMembershipKick) Message type does not exist. Use kick action for removing members.

See: reference/action-index.md for complete list with replacement details and code references.

Common Requirements

Player Requirements

Player Online:

Sufficient Resources:

Struct Requirements

Sufficient Charge:

Sufficient Power:

Command Ship Online:

Fleet Status:

Location Requirements

Valid Location:

Valid Target:

Action Patterns

Pattern 1: Single Action

Use Case: Simple action, no dependencies

Flow:

  1. Check requirements
  2. Build transaction
  3. Sign transaction
  4. Submit transaction
  5. Wait for confirmation
  6. Verify action occurred

Example: struct-activate, struct-deactivate

Pattern 2: Two-Step Action

Use Case: Action requires two steps

Flow:

  1. Step 1: Initiate action
  2. Wait for confirmation
  3. Query state (wait for intermediate state)
  4. Step 2: Complete action
  5. Wait for confirmation
  6. Verify action occurred

Examples:

Pattern 3: Action with Proof-of-Work

Use Case: Action requires proof-of-work computation

Flow:

  1. Initiate action
  2. Wait for confirmation
  3. Query struct state
  4. Compute proof-of-work
  5. Complete action with proof
  6. Wait for confirmation
  7. Verify action occurred

Examples:

See: protocols/action-protocol.md#proof-of-work for proof-of-work details

Pattern 4: Conditional Action

Use Case: Action depends on game state

Flow:

  1. Query game state
  2. Check preconditions
  3. If conditions met: Execute action
  4. If conditions not met: Wait or abort
  5. Verify action occurred

Example: Attack only if target is valid and attackable

Transaction Flow

Complete Flow

{
  "flow": [
    {
      "step": 1,
      "action": "Get account info",
      "endpoint": "GET /cosmos/auth/v1beta1/accounts/{address}"
    },
    {
      "step": 2,
      "action": "Build transaction",
      "message": "Action message (e.g., MsgStructBuild)"
    },
    {
      "step": 3,
      "action": "Sign transaction",
      "method": "Sign with private key"
    },
    {
      "step": 4,
      "action": "Submit transaction",
      "endpoint": "POST /cosmos/tx/v1beta1/txs"
    },
    {
      "step": 5,
      "action": "Wait for confirmation",
      "check": "Transaction status"
    },
    {
      "step": 6,
      "action": "Verify action occurred",
      "method": "Query game state"
    }
  ]
}

See: protocols/action-protocol.md for complete details

Validation Warning

⚠️ IMPORTANT: Transaction status broadcast does NOT mean action succeeded!

Validation happens on-chain after broadcast:

  1. Transaction broadcasts successfully
  2. on-chain validation checks requirements
  3. Action succeeds OR fails based on validation
  4. Always verify game state to confirm action occurred

Example:

{
  "scenario": "Build struct without sufficient resources",
  "result": {
    "transaction": "broadcast",
    "action": "failed",
    "reason": "Insufficient resources (validated on-chain)"
  },
  "verification": "Query struct - struct not created"
}

Error Handling

Common Errors

Player Halted (code: 6):

Insufficient Funds (code: 2):

Insufficient Charge (code: 7):

Invalid Location (code: 8):

Invalid Target (code: 9):

See: api/error-codes.md for complete error catalog

Quick Lookup

By Category

Construction:

Combat:

Resource:

Economic:

Exploration:

Fleet:

Guild:

Permissions:

By Requirement

Requires Proof-of-Work:

Requires Charge:

Requires Command Ship:

Two-Step Process:

Action Definitions:

Protocols:

Patterns:

Examples:

Quick Tips

  1. Always check requirements before submitting action
  2. Verify action occurred by querying game state
  3. Handle errors gracefully with retry logic
  4. Use two-step pattern for build/mining actions
  5. Compute proof-of-work for actions that require it
  6. Wait for confirmations before proceeding
  7. Query game state to verify action success
  8. Handle validation failures appropriately

Last Updated: January 1, 2026