Skip to main content

Cheat Sheet & AI Skill

Full Documentation (Agent Access)​

The skill below is a summary. For full details, fetch the online docs:

  • Index (start here to discover all pages): https://miragenet.github.io/Mirage/llms.txt
  • Individual pages: https://miragenet.github.io/Mirage/docs/<path>.md

Fetch llms.txt first to find the right page, then fetch the specific .md for full detail.

Mirage Code Guidelines

Mirage is a high-level networking library for Unity, built as a hard fork of UNet/Mirror.

Enums​

Mirage.Channel (use full name to avoid collisions)​

  • Mirage.Channel.Reliable (default)
  • Mirage.Channel.Unreliable.

RpcTarget (use full name to avoid collisions)​

  • RpcTarget.Owner
  • RpcTarget.Observers (default)
  • RpcTarget.Player (add INetworkPlayer target as first method parameter to pass what player to target)

Attributes & Options​

[SyncVar]​

Syncs server field to clients. Options:

  • hook: Client method/event name called on value change.
  • initialOnly: Sync only on spawn, ignores future changes.
  • invokeHookOnServer: Fires hook on server. (Note: In Host mode, the hook always fires regardless of this value).
  • invokeHookOnOwner: Fires hook on owner client.
  • hookType: enum SyncHookType values: [Automatic, MethodWith0Arg, MethodWith1Arg, MethodWith2Arg, EventWith0Arg, EventWith1Arg, EventWith2Arg] If field is struct/class, treat it as a property. You can't change sub-fields, the whole value must be set again for mirage to detect changes (like transform.position and .y)

Hook Invoke order​

  • only if value changed
  • on host/server: hook invoked in callstack that SyncVar is set
  • on client
    • on spawn: (before OnStartClient) all SyncVars for that Behaviour are set, then hooks are invoked (if value changed).
      • note: this is per class, base class will have their SyncVar and hooks invoked before child class runs theirs.
    • on change: value is set, then hook is invoke (if value changed), then next syncvar/hook is set/invoked.

Sync Direction (Inspector / Component Settings)​

Configures which side acts as the source of truth for [SyncVar] properties on a NetworkBehaviour:

  • Server -> Owner, Observers (Default / Recommended):
    • Server updates [SyncVar] values (e.g. inside [ServerRpc] or server timers), which replicate down to the Owner client and Observers.
    • Required for server-authoritative abilities, duration timers, or health systems.
  • Owner -> Observers, Server (Owner Authority):
    • Owner client directly mutates [SyncVar] fields on its local client, replicating to Server and Observers.
    • Warning: When set to Owner direction, server-side SyncVar assignments will not replicate back to the Owner client, causing Owner/Server desync if the server attempts to manage state.
  • Owner,Server -> Owner,Server (bidirectional):
    • this allows either owner or server to set a syncvar and have to replicated to each other
    • add Observers as well to have server forward changes to other clients
    • this has desync risk if both owner and server set value at the same time, both will send update message causing race condition

[ServerRpc]​

Invoked on server from client. Options:

  • channel: Mirage.Channel enum
  • requireAuthority: Requires client authority (default true).
  • allowServerToCall: Allows local server execution bypassing authority (default false). Add INetworkPlayer sender = null as last parameter if validation is needed (only useful if requireAuthority=false) Can have return value using UniTask<MyValue>

[ClientRpc]​

Invoked on clients from server. Options:

  • channel: Mirage.Channel enum
  • target: RpcTarget enum
  • excludeOwner: Excludes owner client from execution.
  • excludeHost: Stops execution on host/server. Can have return value using UniTask<MyValue> (if target is Owner or Player)

Metadata Attributes​

  • [NetworkMessage]: Generates reader/writer for class/struct. Mostly an optional hint.

Security [RateLimit]​

Applies rate limiting to [ServerRpc] Options:

  • Interval: Refill Interval, in seconds (default 1f).
  • Refill: Refill per interval (default 50).
  • MaxTokens: Bucket capacity (default 200).
  • Penalty: Error Cost if bucket is empty (default 1).

Security [MaxLength]​

Enforces a limit on the size of serialized strings, arrays, or lists to protect against memory allocation attacks

  • Apply to [ServerRpc] parameters, SyncVar or NetworkMessage fields.
  • Enforces char/element count.
  • Client does check before sending and throws SerializationLimitException is limit is hit to avoid sending
  • Example:
    • Field: [MaxLength(32)] public string PlayerName;
    • RPC parameters: public void CmdUpdateName([MaxLength(24)] string name)

Events/Callbacks​

NetworkIdentity (Register in Awake)​

  • OnStartServer: Invoked while spawning, before SpawnMessage is sent
  • OnAuthorityChanged(bool): Authority given/removed. Called before right OnStartClient when spawning
  • OnStartClient: Invoked while spawning, after SyncVars (and hooks) are set
  • OnStartLocalPlayer: Called right after OnStartClient, if make character for player
  • OnOwnerChanged(INetworkPlayer): Owner assigned (server-only).
  • OnStopClient: Unspawned/destroyed on client.
  • OnStopServer: Unspawned on server.

NetworkServer (Register anywhere)​

  • Started: Called when server starts (in host mode, called before host is connected)
  • Stopped: Server start/stop. (use)
  • Authenticated(INetworkPlayer player): Player fully connected, (use this instead of Connected)
  • Disconnected(INetworkPlayer player)
  • OnStartHost / OnStopHost: Host mode start/stop.

NetworkClient (Register anywhere)​

  • Started: Called when client starts (in host mode, called before host is connected)
  • Authenticated: Player fully connected, (use this instead of Connected)
  • Disconnected(ClientStoppedReason reason): Called when Disconnect.

Player Error Handling​

INetworkPlayer has SetError(int cost, PlayerErrorFlags flags) method that can be used to flag errors caused by players. Players will then be disconnected if they cause too many errors in a short amount of time.

Enum Flags PlayerErrorFlags​

  • None Mirage Flags
  • RpcNullException throw inside RPC
  • RpcException throw inside RPC
  • DeserializationException throw inside NetworkReader
  • RpcSync RPC internal values incorrect, likely out-of-date build
  • RateLimit
  • NoAuthority no object authority
  • Unauthenticated NetworkMessage sent before authentication was finished
  • Critical other errors, likely cheater, should be kicked right away
  • LikelyCheater
  • CustomError custom errors that can be set by game, starting at 1 << 16