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.

  • Lives on the same GameObject as HealthSystem
  • 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