Skip to content

Health Authority

Folder Overview

This folder defines the authority gating seam used by HealthSystem to allow or deny mutations.

Replication, prediction, rollback, and reconciliation are out of scope.

Purpose

Authority acts as a gate for mutation.

It answers one question:

Is this mutation allowed right now?

What Lives Here

The authority system is:

  • Runtime-only
  • Netcode-agnostic
  • Opt-in via HealthSystem.requireAuthority
  • Built around the public IHealthAuthority contract

Important Notes

Boundaries

This is not:

  • A networking layer
  • A replication system
  • An ownership model
  • A prediction or reconciliation framework

These concerns belong to your networking layer.

Components

Core Contract — IHealthAuthority

bool HasAuthority(IHealthReadonly health);

Semantics:

  • Returns true → mutation is allowed
  • Returns false → mutation is denied

No side effects. No state changes.

health.SetAuthorityResolver(() => /* return true when allowed */);
  • Used when requireAuthority is enabled
  • Allows integration with netcode ownership, server checks, or prediction logic
  • Keeps Health decoupled from specific networking frameworks

To remove the injected policy:

health.ClearAuthorityResolver();

Component-Based Authority

You may:

  • Attach the built-in HealthAuthorityBinder
  • Or provide your own MonoBehaviour : IHealthAuthority

When no resolver is injected, HealthSystem attempts to resolve an IHealthAuthority component in the scene.

Built-in Binder — HealthAuthorityBinder

A permissive implementation intended for local play and testing.

  • Can live on the HealthSystem's GameObject, on an ancestor, or anywhere in the scene. Nearest wins — the object being gated, then its parents, then the scene — and the two hierarchy steps are not cached, so an actor carrying its own authority is governed by that one whatever resolved first
  • alwaysTrue = true allows local mutation
  • Invalidates the scene authority cache on enable/disable

In multiplayer scenarios, prefer resolver injection.

Usage Guidance

How HealthSystem Uses Authority

When requireAuthority is OFF:

  • Authority is ignored
  • All mutations are allowed

When requireAuthority is ON:

  • Every mutating call is gated

  • If denied:

  • Mutation is blocked

  • LastAuthorityError is populated (display-only)
  • AuthorityDenied event is raised

Authority only gates mutation.

It does not affect damage/heal pipelines, replication, or event ordering.

Usage Patterns

Single-player

  • Leave requireAuthority = OFF
  • Or enable it and add HealthAuthorityBinder

Multiplayer (authoritative)

  • Enable requireAuthority
  • Inject a resolver via SetAuthorityResolver
  • Perform mutations on the authoritative side
  • Replicate results using your networking layer

Important Notes

Boundaries

Do not:

  • Assume this provides networking
  • Bypass authority checks
  • Mutate health from non-authoritative contexts
  • Embed gameplay rules into authority resolution

Authority is a guardrail, not a gameplay system.

  • Health System
  • Health Abstractions