Runtime and state
Namespace: StellarStriderLib. Configuration properties are get/set. SSLib supplies PartInstance and PartState.
Source: PartServices.cs. For a complete recipe, see Runtime callbacks and state.
BoxShape
Part-local box, independent of visual scale and explicit placement size.
| Property | Type | Default | Meaning |
|---|---|---|---|
Center | UnityEngine.Vector3 | zero | Centre in part-local metres |
Size | UnityEngine.Vector3 | one | Finite positive dimensions |
Rotation | UnityEngine.Vector3 | zero | Euler rotation in degrees |
Transforms must be finite. Each supplied box array is non-null and contains at most 256 non-null boxes. Static solid overrides are rejected for donors with dynamic colliders. See Sockets and shapes.
InteractionShapeDefinition
| Property | Type | Default | Meaning |
|---|---|---|---|
Target | string | null | Unique donor interaction GameObject name, or select the sole interaction |
Boxes | BoxShape[] | empty | Replacement trigger boxes; empty removes the target's colliders |
A part can declare at most 32 interaction targets. Targets must be unique and resolve exactly once. Native actions and their enable/disable hierarchy are retained; this does not register new actions.
PartCallbacks
All delegates default to null and run on Unity's main thread.
| Property | Delegate type | Timing |
|---|---|---|
Spawned | Action<PartInstance> | Once when this role observes the instance |
Removed | Action<PartInstance> | Native removal, client despawn, or world teardown |
ServerTick | Action<PartInstance, float> | After native server simulation; float is delta time |
ClientUpdate | Action<PartInstance, float> | Once per loaded native visual update; float is delta time |
NativeStateChanged | Action<PartInstance, StatefulPartStateChangeEvent> | After native part-state changes |
StateChanged | Action<PartInstance> | Coalesced custom field changes at the next callback flush |
Action is from System; StatefulPartStateChangeEvent is from Ships.Interface.Model.Parts.
Hosts have separate server/client instances. Exceptions disable the failing callback for that instance and are logged. Removal keeps a readable final snapshot; writes stop.
PartInstance
A single role's runtime view. Public properties are read-only; the native part may be refreshed internally.
| Property | Type | Meaning |
|---|---|---|
Id | Ships.Interface.Model.Parts.PartContext | Native ship/part identity; includes ShipId and PartId |
ContentKey | string | Registered part's full key |
IsServer | bool | This is the authoritative server role |
Ship | Ships.Interface.Model.State.IShipStateRead | Native read-only ship state |
Part | Ships.Interface.Model.Parts.StatefulPart | Native stateful part |
State | PartState | Declared custom state access |
IsActive | bool | Instance is still live |
Do not retain an instance beyond its lifetime or use it to access a replacement at the same ID.
PartStateField
| Property | Type | Default | Meaning |
|---|---|---|---|
Name | string | null | Required unique, nonblank name, at most 64 characters |
Default | Newtonsoft.Json.Linq.JToken | null | Required non-null JSON default defining the field's top-level type |
Saved | bool | true | Include field in the state sidecar |
Replicated | bool | true | Send field to clients |
Unsaved fields reset on load. Non-replicated fields stay at defaults on clients. Defaults may be objects, arrays, strings, booleans, integers, or finite floats. Only nested values may be null.
PartStateDefinition
| Property | Type | Default | Meaning |
|---|---|---|---|
Version | int | 1 | Positive saved-state schema version |
Fields | PartStateField[] | empty | Non-null, at most 128 fields |
Migrate | Func<int, JObject, JObject> | null | Convert an older saved version directly to current saved fields |
Validate | Action<JObject> | null | Throw to reject complete proposed state; do not mutate it |
Func/Action are from System; JObject is from Newtonsoft.Json.Linq.
Validation runs on defaults, authoritative changes, and restored values. Replica validation uses types and replication flags without applying the full validator to hidden fields. State is limited to nesting depth 16 and 16 KiB of UTF-8 JSON per complete part state.
Migration receives the old version and a copy of saved fields. Return current saved fields only; omitted fields receive defaults. Invalid/future versions, missing migration, and invalid results fail loading. Keep schemas unchanged after registration.
PartState
Server-owned JSON access. All operations enforce the main thread.
public T Get<T>(string field);
public Newtonsoft.Json.Linq.JObject Snapshot();
public void Set<T>(string field, T value);
public void Set(Newtonsoft.Json.Linq.JObject fields);Get<T>reads a declared field and converts a copy toT. Unknown fields throw.Snapshotreturns a deep copy of the complete current state, or the final snapshot after removal. Modifying the returned object does not commit anything.Set(field, value)updates one field using the same checks as the multi-field overload.Set(JObject)merges supplied fields into the current state, validates the whole proposed state, and commits atomically. Omitted fields retain their values. Identical changes are ignored.
Only a live server instance can write. Null update objects, unknown fields, top-level type mismatches, nonfinite numbers, excessive size/depth, or validator failures reject the update. Integer values are accepted for floating fields. Objects and arrays must be committed back after editing a read copy.
Client state contains the selected replicated fields plus defaults for hidden fields. Being the host does not give a client-role instance permission to write.