ReferenceManager

The ReferenceManager class is a Lua script that allows you to manage and keep track of references that meet specific requirements. This class enables you to add, remove, and iterate through active references while executing custom callback functions when references are activated. Additionally, it supports registering multiple reference managers, each with its own set of requirements and callbacks.

References that meet the requirements for the reference manager will be automatically added to the manager's reference list when that reference is activated, and removed from the list when it is deactivated (i.e invalidated or deleted). Referenecs are also removed from the list if they no longer meet the requirements when referenceManager:iterateReferences is called.

Fields

Name	Type	Description
id	string	The ID of the registered manager. If provided, the manager can be accessed with ReferenceManager.get(id).
requirements	function(self, tes3reference)	A function that takes a tes3reference as input and returns a boolean value indicating whether the reference is valid for this manager.
onActivated	function(self, tes3reference)	A callback function that is triggered when a reference is activated.
references	table<tes3reference, any>	A set of active references that have been added to the manager. Each reference is associated with an empty table for custom data.

Static Methods

Name	Parameters	Returns	Description
ReferenceManager:new	params: constructorparams	ReferenceManager	Constructs a new instance of the ReferenceManager class. If id is provided, the manager is registered.
ReferenceManager.get	id: string	ReferenceManager	Retrieves a registered reference manager by its ID.
ReferenceManager.registerReference	reference: tes3reference	-	Registers a reference against any valid managers. Called when a reference is activated.
ReferenceManager.unregisterReference	reference: tes3reference	-	Unregisters a reference from any managers it is no longer valid for. Called when a reference is deactivated.

Methods

Name	Parameters	Description
ReferenceManager:addReference	reference: tes3reference	Adds a reference to the manager. The reference is associated with an empty table in references.
ReferenceManager:removeReference	reference: tes3reference	Removes a reference from the manager.
ReferenceManager:iterateReferences	callback: fun(ref: tes3reference, refData: any)	Executes a callback for each reference in the manager.

Events

The class also handles two MWSE events for reference activation and deactivation:

referenceActivated Event

• Event Data: referenceActivatedEventData
• Description: Triggered when a reference is activated. It calls ReferenceManager.registerReference(e.reference).

referenceDeactivated Event

• Event Data: referenceDeactivatedEventData
• Description: Triggered when a reference is deactivated. It calls ReferenceManager.unregisterReference(e.reference).

ConstructorParams

The ReferenceManager constructor accepts a table of parameters with the following fields:

Name	Type	Description
requirements	function(self, tes3reference)	A function that takes a tes3reference as input and returns a boolean value indicating whether the reference is valid for this manager.
id	string (optional)	The ID of the registered manager. If provided, the manager can be accessed with ReferenceManager.get(id).
onActivated	function(self, tes3reference) (optional)	A callback function that is triggered when a reference is activated.
logger	mwseLogger (optional)	A logger to use for this manager. If not provided, a logger will be created with the ID of the manager. If no ID is provided, the default ReferenceManager logger will be used.

Example Usage

-- Load the required dependencies (MWSE and CraftingFramework.util.Util) before using the ReferenceManager class.

-- Define a requirements function.
local function isValidReference(_, reference)
    -- Add your custom logic to determine if the reference is valid for this manager.
    return ref.object.objectType == tes3.objectType.npc
end

-- Create a new ReferenceManager instance.
local manager = CraftingFramework.ReferenceManager:new{
    requirements = isValidReference,
    onActivated = function(ref)
        -- Custom logic to execute when a reference is activated.
        tes3.messageBox("Reference %s has been activated!", ref.id)
    end,
    id = "NPCManager", -- Optional ID for accessing the manager later.
}

-- Access the registered manager by its ID.
local retrievedManager = CraftingFramework.ReferenceManager.get("NPCManager")

-- Use the retrievedManager to add, remove, or iterate through references.

-- Register a reference with the manager.
local someReference = tes3.getReference("SomeReferenceID")
retrievedManager:addReference(someReference)

-- Iterate through the references and execute a callback function.
retrievedManager:iterateReferences(function(ref, refData)
    -- Custom logic for handling each reference.
    tes3.messageBox("Iterating through reference %s", ref.id)
end)

-- Unregister a reference from the manager.
retrievedManager:removeReference(someReference)