Skip to content

Modifiers Subsytem

Jump to bottom
iiw2012 edited this page Sep 4, 2024 · 25 revisions

Description

Modifiers are scripts bound to the device that perceive various events around it and generate responses. For example, a modifier adds gold to the inventory when the player removes the device. Modifiers have certain properties and restrictions that they obey:

  • Each device can have no more than one modifier of each type.
  • Modifiers can be set in the armor script in esp, and/or added by the patcher when the device first appears in the inventory.
  • Modifier settings are set during its generation and are not changed afterwards.
  • Modifier settings of the same type are stored individually for each device.
  • Modifiers are processed only on equipped devices. And some events handled only for the player.

Implementation

The modifier subsystem consists of several parts:

  • Modifier Manager - coordinates the whole system, collects and passes events to modifiers.
  • Modifiers Storages - self-registering containers of created modifiers.
  • Configuration - each device has properties for storing configurations of applied modifiers.
  • Patcher - Patcher can also be used to distribute modifiers on devices, so it can be referred to this subsystem, although it is not a mandatory part of it.
  • There are also separate quests, scripts and methods that are scattered throughout the framework and help to collect events for the manager.

Modifier Manager

Scriptname UD_ModifierManager_Script extends Quest

Modifiers Storages

ScriptName UD_ModifierStorage extends Quest

To make Modifiers Storage all you need to do is create a quest, bind the UD_ModifierStorage script to it, and add modifiers aliases. See UD_ModifierSlots_Quest Quest for the reference.

Base modifier script

Scriptname UD_Modifier extends ReferenceAlias

Configuration data

Scriptname UD_CustomDevice_RenderScript extends ObjectReference  

; <...>

Alias[]     Property UD_ModifiersRef          auto
String[]    Property UD_ModifiersDataStr      auto
Form[]      Property UD_ModifiersDataForm1    auto
Form[]      Property UD_ModifiersDataForm2    auto
Form[]      Property UD_ModifiersDataForm3    auto
Form[]      Property UD_ModifiersDataForm4    auto
Form[]      Property UD_ModifiersDataForm5    auto

Event processing

Almost all events go through a manager that calls the appropriate modifier methods on all devices of registered actors.

Modifier processor list

Function GameLoaded()
Function TimeUpdateSecond(Float afTime)
Function TimeUpdateHour(Float afMult)
Function Orgasm()
Function DeviceLocked()
Function DeviceUnlocked()
Function MinigameStarted(UD_CustomDevice_RenderScript akMinigameDevice)
Function MinigameEnded(UD_CustomDevice_RenderScript akMinigameDevice)
Function WeaponHit(Weapon akWeapon, Float afDamage)
Function SpellHit(Form akSpell, Float afDamage)
Function SpellCast(Spell akSpell)
Function ConditionLoss(Int aiCondition)
Function StatEvent(String asStatName, Int aiStatValue)
Function Sleep(Float afDuration, Bool abInterrupted)
Function ActorAction(Int aiActorAction, Form akSource)
Function KillMonitor(ObjectReference akVictim, Int aiCrimeStatus)

Custom modifiers

Custom modifier or modifier in general - a type of modifier that is created as a standalone script with a complete logic of reaction to external events. It, like any modifier, can have flexible customization, but, in general, acts according to the same template. On the other hand, this pattern of actions can be very complex, as the script can take into account all possible events, and the outcome is limited only by the developer's imagination.

List of (custom) modifiers

See https://github.com/iiw2012/UnforgivingDevices/wiki/Modifiers-List#custom-modifiers

Combo modifiers

Combo modifiers (CMs) are a subclass of modifiers that consist of a trigger script (hereafter just Trigger) and an outcome script (hereafter just Outcome) that are selected from predefined lists and can be used in any combination. CM forwards incoming events to the Trigger, and when it responds (returns true), the Outcome procedure is executed.

Base class for the CM is implemented in the file:

ScriptName UD_Modifier_Combo extends UD_Modifier

Like any other modifier CM uses the configuration stored in the device properties, but with certain caveats:

  • The arguments in DataStr are shared between the Trigger and the Outcome. Indexes 0..6 are used in the Trigger, and all subsequent indexes are used in the Outcome. It is potentially possible to pass information between the Trigger and the Outcome using these arguments, but this is not used anywhere right now.
  • DataForm1 - stores the trigger script.
  • DataForm2 - stores the outcome script.
  • DataForm3 - passed to the Trigger.
  • DataForm4 - passed to the Outcome.
  • DataForm5 - passed to the Outcome.

As an example, consider the following configuration of property values on a device.

UD_ModifiersRef[0]        = <UD_Modifier_Combo>             ; alias with generic combo modifier script on it 
UD_ModifiersDataStr[0]    = "DU,50.0,,,,,,1,3,0"            ; 0..6 arguments for the Trigger, all of the following arguments for the Outcome
UD_ModifiersDataForm1[0]  = <UD_ModTrigger_DeviceEvent>     ; MiscForm with attached trigger script
UD_ModifiersDataForm2[0]  = <UD_ModOutcome_AddItem>         ; MiscForm with attached outcome script
UD_ModifiersDataForm3[0]  = None                            ; is passed to the Trigger
UD_ModifiersDataForm4[0]  = <Lockpick>                      ; is passed to the Outcome
UD_ModifiersDataForm5[0]  = None                            ; is passed to the Outcome

The UD_ModTrigger_DeviceEvent trigger reacts to manipulation of its own device and the first 7 arguments from the DataStr (DU,50.0,,,,,) along with DataForm3 are passed to it. This causes the trigger to activate on the DeviceUnlock event with a 50% probability. The procedure from the outcome script will then be called with the remaining arguments from DataStr (1,3,0) and DataForm4, DataForm5. The given values for the Outcome will have the following effect: 1-3 lockpicks will be added to the player's inventory.

Generic Combo Modifiers

The example above showed one way in which CM can be used. When a template combo-modifier is added to the device, and then filled with the desired trigger, outcome and configuration for them. There are several such templates made for this use case, which lie in the UD_ModifierSlotsCMB_Quest storage. CMN1 .. CMN5 for the modifiers with the negative effects and CMP1 .. CMP5 for the modifiers with the positive effects.

This approach allows you to quickly create modifiers of any degree of insanity, but it also has its limitations:

  • It is impossible to predict and prevent conflicts between modifiers.
  • You have to settle for a generic name and description.
  • They can't be used with the Patcher (at least not in any reasonable way).

Usage

  1. Add one of the generic combo modifiers to the device (CMN1..5 or CMP1..5 from quest UD_ModifierSlotsCMB_Quest)
  2. Complete the configuration similar to the example above, namely:
    1. DataFrom1 - Trigger.
    2. DataForm2 - Outcome.
    3. Other properties fill according to the description of the trigger and outcome.

Triggers

The trigger accepts incoming event information from the modification manager and returns either true or false. It can also write some information into DataStr parameters to implement “memory-aware” algorithms. It essentially repeats the work of a regular modifier, but with limited capabilities and with one type of reaction: true/false.

Implementation

Base class for the Trigger is implemented in the file:

Scriptname UD_ModTrigger extends MiscObject

Every Trigger should be placed on unique MiscObject in esp.

List of Triggers

See https://github.com/iiw2012/UnforgivingDevices/wiki/Modifiers-List#triggers

Outcomes

The Outcome of a combo modifier is essentially a simple procedure that performs one action according to the passed configuration.

Implementation

Base class for the Outcome is implemented in the file:

Scriptname UD_ModOutcome extends MiscObject

Every Outcome should be placed on unique MiscObject in esp.

List of Outcomes

See https://github.com/iiw2012/UnforgivingDevices/wiki/Modifiers-List#outcomes

Presets for combo modifiers

Another way to use CM is to create presets: separate aliases with pre-defined Trigger and Outcome. These presets do not require custom scripts, but allow you to use it as a regular modifier: set names and descriptions and assign with the Patcher.

Implementation

ScriptName UD_Modifier_ComboPreset extends UD_Modifier_Combo

UD_ModTrigger Property ModTrigger Auto
UD_ModOutcome Property ModOutcome Auto
<...>

List of combo modifiers presets

See https://github.com/iiw2012/UnforgivingDevices/wiki/Modifiers-List#combo-modifiers-presets

Usage

  1. Add new quest alias on Modifier Storage Quest.
  2. Attach UD_Modifier_ComboPreset quest to the created alias.
  3. Fill properties ModTrigger and ModOutcome with appropriate values.
  4. Use the created modifier in devices with configuration according to the trigger and outcome descriptions.

Patcher and modifiers

Global Patcher Settings

Int         Property UD_ModsMinCap          =    2    Auto Hidden   ; If the number of modifiers is lower than the specified value, we try to add more modifiers
Int         Property UD_ModsSoftCap         =    4    Auto Hidden   ; soft cap for the number of modifiers added by the patcher (the number of mods may exceed this value, as the probability of adding a mod is determined by the mod itself)
Int         Property UD_ModsHardCap         =    99   Auto Hidden   ; hard cap for the number of modifiers added by the patcher (when this value is reached, the patcher stops adding mods)

Float       Property UD_ModGlobalProbabilityMult    = 1.0   Auto Hidden
Float       Property UD_ModGlobalSeverityShift      = 0.0   Auto Hidden
Float       Property UD_ModGlobalSeverityEasing     = 1.0   Auto Hidden

Possible conflicts resolution

TODO: Use a tagging system instead of checking by name.

A list of space-separated tags that reflect the nature of the modifier. Used to resolve possible conflicts during automatic generation. Each tag is a short abbreviation. Some tags may be accompanied by a "+" or "-" sign, which reflect the positive or negative effect of the modifier.

For example:

  • GOLD+ - the modifier gives the actor gold. Adding modifiers with GOLD+ and GOLD- tags may cause a conflict.
  • EVL - the modifier causes the device to evolve. Modifiers with some other handlers on device removal event may conflict with this tag.
  • UNQ - the modifier has a unique (quest) effect. Adding other modifiers with this tag can lead to unpredictable results.

Presets for the Patcher

Scriptname UD_Patcher_ModPreset extends ReferenceAlias Hidden

Override behaviour

Bool Function PatchModifierFastCheckOverride(UD_CustomDevice_RenderScript akDevice)
Float Function PatchModifierCheckAndAddOverride(UD_CustomDevice_RenderScript akDevice)

Clone this wiki locally