Asset Distribution and Late-Join Behaviour

Remote content is a bounded, authenticated flow for custom-item PNG icons, existing-object PNG texture overrides, and supported OGG audio. It is not a general remote asset or spawning system.

Connection flow

The server authenticates the client.
It offers an immutable item catalog and file manifest.
The client displays a consent decision bound to the server fingerprint, catalog SHA-256, and manifest SHA-256.
A decline sends no file requests and activates no content.
An approval requests only missing allowed files and enters Transferring.
Once those files have arrived and passed transfer validation, readiness becomes Transferred.
The client stages every stock-template clone, PNG decode, icon, text entry, and collision check.
It publishes all items atomically or rolls everything back.
The client acknowledges only the exact activated catalog digest, advancing readiness to Activated.

A changed server, catalog, or manifest tuple requires new consent. Content readiness belongs to the current player instance. Native round restart can preserve the authenticated connection while replacing the player; the new player receives a fresh offer and activates again. Matching persisted approval reuses cached files without another prompt. An undecided or declined offer may prompt again.

Transferred is deliberately not grant-ready. It separates verified byte delivery from successful client materialization and activation.

Players may leave the content consent prompt open without a timeout. Waiting for a decision reserves no active-transfer slot or byte budget. The 30-second transfer inactivity deadline begins after explicit approval, including when the client never sends its file request. Declining keeps the player connected.

Custom-item contract

Each definition contains a lowercase colon-separated stable key, a valid stock base item, display name, optional description, and optional PNG icon. IDs are assigned transactionally above the current stock maximum up to 127.

A custom item inherits the stock base’s model, pickup, behavior plumbing, and weight. V1 does not support custom roles, effects, models, weights, bundles, meshes, or generic remote spawning.

Server companions should use:

CustomItems.TryGetItemId and CustomItems.TryGetItemKey.
CustomItems.IsCustomItem.
CustomItems.GetPlayerReadiness.
The once-per-activation ClientEvents.ContentReady event.
CustomItems.TryGiveItem, which remains gated on matching activation.

Cache and provenance

Physical blobs use a shared SHA-256 cache. Consent and activation records are scoped separately to server fingerprint and catalog. Startup reconciliation quarantines corrupt, orphaned, temporary, or over-budget cache material rather than trusting filenames.

Cache possession is never authorization. The server sends texture overrides and announcer vocabulary only to clients whose completed approved manifest contains the exact hash with the expected PNG or OGG kind, and the client applies the same exact-membership check before decoding a cached resource.

The transfer envelope permits at most 64 MiB per file and 256 MiB per manifest. Actual decoding is stricter: encoded PNG is capped at 16 MiB, 4096 pixels per dimension, and 16 Mi pixels; encoded OGG is capped at 32 MiB, two channels, 8-96 kHz, and 30 seconds. A retained decoded asset is capped at 64 MiB, with separate peak and aggregate decode budgets. Headers and metadata are validated before large allocations.

File changes and late join

File-watcher changes and deletions rebuild offers for future player instances, including reconnects and native round restarts. An active player keeps its approved snapshot; no destructive hot reload is broadcast.

Round and other non-asset state are independent of file transfer. An authenticated late joiner receives non-asset state before content approval; a deliberate decline keeps that connection, while transfer failure disconnects. Item-dependent grants wait for successful activation.

Continue to Troubleshooting and Known Limitations.