Modding:Active Parts

Many object parts (the entity components specified in  with   tags) are based on   architecture. provides standardized support functionality for parts that actively, conditionally enact behavior. Much of this support can be powerfully reconfigured at the object blueprint level without requiring scripting intervention, though whether a given variation in behavior will actually work depends on the quality of the final part's integration with.

The most crucial concepts to how active parts work are subjects, the objects the part operates on, and status, the part's operational state. The basic form of a part's integration with its  support is for it to check its status, and if it is operational, to apply its behavior to its subjects.

Statuses
These are the possible active part statuses. Only the status Operational represents working functionality; other statuses are failure modes.

Statuses are evaluated in the order listed. If more than one status potentially applies, the earlier one is used.

Status-determining configuration points
The following configuration points control the determination of an active part's status. Defaults indicated are at the  level. Many individual parts set different defaults, and in particular see IPoweredPart.

Individual parts can also override the method  to implement their own failure modes; if this method returns true, the part's status will be LocallyDefinedFailure. Generally  should also be overridden; its return value will be used instead of "LocallyDefinedFailure" for status display (see below).

Subject-determining configuration points
The following boolean configuration points control identification of an active part's subject or subjects. All default to false at the  level. Many individual parts set different defaults.

Individual parts can also override the method  in order to implement additional restrictions on what objects are valid subjects.

If an active part has no valid subjects, its status will be NeedsSubject.

Where the parent object's current cell is referred to, it only applies to a cell the parent object is directly present in (not a cell its carrier or equipper is in, for example).

Status display configuration points
These fields control the display of the active part's status in the parent object's short description.

IPoweredPart
The majority of active parts inherit, which is a variant of   intended for more technical applications. It sets the following defaults:

Introduction
The most common way for parts to use  support is the   method. The example part below heals its parent object every turn:

In this very basic integration, the  parameter makes the part consume the amount of charge in its   field. Without further configuration, this will have defaulted to 0. We want to call for charge to be used as the appropriate time to enable specific configurations that do use charge to be created.

The part above is directly acting on its parent object, without checking any information about subjects provided by. It sets  because without any identifiable subject, the part will not be operational. Instances could set other subject-determining configuration points, which could change when the part works (since it won't work without a subject), but won't change what object the healing is applied to. A more flexible integration could look like:

This part will need subject-determining configuration before it can operate. It will apply its healing to whatever subject or subjects are identified by that configuration, though, making it more powerful for designers to work with.

IsReady
Returns true if the part's status is Operational. Triggers any appropriate render color changes. Updates the last known status.

IsDisabled
The same as, but with the opposite return value.

GetActivePartStatus
Like, but returns an   that can be used to determine what failure mode the part is in. Useful for constructing more helpful failure messaging.

Triggers any appropriate render color changes. Updates the last known status.

WasReady
Returns whether the active part's status was Operational the last time it was evaluated.

WasDisabled
Returns whether the active part's status was other than Operational the last time it was evaluated.

GetLastActivePartStatus
Returns what the active part's status was the last time it was evaluated.

ConsumeCharge
Triggers consumption of charge from the parent object, irrespective of operational status. The  parameter can be used to override the part's   setting; the default of null means do not override.

As above, but  has the same behavior as for.

ConsumeChargeIfOperational
Triggers consumption of charge from the parent object if the part is operational. Parameters that are also present in  behave the same as there.

Normally, status will only be obtained (and therefore color changes triggered and last known status updated) if there is any charge consumption to be performed. can be set to true to indicate that status should always be obtained.

GetActivePartSubjects
Returns a list of the active part's current subjects.

GetActivePartFirstSubject
Returns the active part's first subject, or null if it has none.

Returns the first of the active part's subjects that matches the filter specified, or null if none do.

IsObjectActivePartSubject
Returns whether the object specified is one of the active part's subjects.

ActivePartHasMultipleSubjects
Returns whether the active part has at least two subjects.

GetActivePartSubjectCount
Returns how many subjects the active part has.

ForeachActivePartSubjectWhile
Calls  on each of the active part's subjects, terminating if   returns false.

should be set to true if the code in  might result in any object being moved, created, or destroyed; otherwise, there is a risk of exceptions being thrown due to loop control disruption.

AnyActivePartSubjectWantsEvent
For integration with the  system. Returns true if any of the active part's subjects want to receive the event designated.

ActivePartSubjectsHandleEvent
For integration with the  system. Sends the event to each of the active part's subject, terminating early and returning false if any of the event handlers return false.

GetActivePartLocallyDefinedFailure
Intended to be overridden by inheritors to define their own failure conditions. Returns false by default; a locally defined failure will be considered to exist if it returns true.

GetActivePartLocallyDefinedFailureDescription
Intended to be overridden by inheritors to define the description to provide in status display for their own failure conditions. Returns null by default; a non-null return value will be used in place of "LocallyDefinedFailure" when displaying a LocallyDefinedFailure status.

IsActivePartEngaged
Intended to be overridden by inheritors to define whether the part is "engaged" for purposes of. Returns  by default.

GetStatusSummary
For the specified status value, returns a string summary intended for player visibility. Some statuses return null, generally because it makes less sense to present them to the player. The status summaries are:

Can be overridden by inheritors to provide a status summary for LocallyDefinedFailure status or otherwise alter the default behavior.

Returns.

AddStatusSummary
Retrieves  and, if it is not null or empty, appends , the summary, and   to the StringBuilder passed. This is to support code like this:

GetOperationalScopeDescription
Returns a readable general description of what objects the part operates on, based on its subject-determining configuration points. Example return values might be "its user" or "itself and its vicinity".