/tg/ Station 13 - Modules - TypesVar Details - Proc Details

datum

The absolute base class for everything

A datum instantiated has no physical world prescence, use an atom if you want something that actually lives in the world

Be very mindful about adding variables to this class, they are inherited by every single thing in the entire game, and so you can easily cause memory usage to rise a lot with careless use of variables at this level

Vars

_active_timersActive timers with this datum as the target
_datum_componentsComponents attached to this datum
_listen_lookupAny datum registered to receive signals from this datum is in this list
_signal_procsLazy associated list in the structure of target -> list(signal -> proctype) that are run when the datum receives that signal
_status_traitsStatus traits attached to this datum. associative list of the form: list(trait name (string) = list(source1, source2, source3,...))
datum_flagsDatum level flags
filter_dataList for handling persistent filters.
gc_destroyedTick count time when this object was destroyed.
open_uisOpen uis owned by this datum Lazy, since this case is semi rare
tgui_shared_statesglobal
weak_referenceA weak reference to another datum

Procs

AddElementTraitUsed to manage (typically non_bespoke) elements with multiple sources through traits so we don't have to make them a components again. The element will be later removed once all trait sources are gone, there's no need of a "RemoveElementTrait" counterpart.
DestroyDefault implementation of clean-up code.
GenerateTagGenerate a tag for this /datum, if it implements one Should be called as early as possible, best would be in New, to avoid weakref mistargets Really just don't use this, you don't need it, global lists will do just fine MOST of the time We really only use it for mobs to make id'ing people easier
GetComponentReturn any component assigned to this datum of the given type
GetComponentsGet all components of a given type that are attached to this datum
GetExactComponentReturn any component assigned to this datum of the exact given type
RegisterSignalRegister to listen for a signal from the passed in target
RegisterSignalsRegisters multiple signals to the same proc.
RemoveComponentSourceRemoves a component source from this datum
TakeComponentTransfer this component to another parent
TopicCalled when a href for this datum is clicked
TransferComponentsTransfer all components to target
UnregisterSignalStop listening to a given signal from target
_AddComponentCreates an instance of new_type in the datum and attaches to it as parent
_AddElementFinds the singleton for the element type given and attaches it to src
_LoadComponentGet existing component of type, or create it and return a reference to it
_RemoveElementFinds the singleton for the element type given and detaches it from src You only need additional arguments beyond the type if you're using ELEMENT_BESPOKE
_SendSignalInternal proc to handle most all of the signaling procedure
_clear_signal_refsOnly override this if you know what you're doing. You do not know what you're doing This is a threat
add_filter
add_traitsProc that handles adding multiple traits to a target via a list. Must have a common source and target.
change_filter_priorityUpdates the priority of the passed filter key
deserialize_jsonDeserializes from JSON. Does not parse type.
deserialize_listAccepts a LIST from deserialize_datum. Should return whether or not the deserialization was successful.
dump_harddel_infoReturn text from this proc to provide extra context to hard deletes that happen to it Optional, you should use this for cases where replication is difficult and extra context is required Can be called more then once per object, use harddel_deets_dumped to avoid duplicate calls (I am so sorry)
get_filterReturns the filter associated with the passed key
get_filter_indexReturns the indice in filters of the given filter name. If it is not found, returns null.
jatum_new_arglistGets the flat list that can be passed in a new /type(argslist(retval)) expression to recreate the datum. Must only return a list containing values that can be JATUM serialized
modify_filter
processThis proc is called on a datum on every "cycle" if it is being processed by a subsystem. The time between each cycle is determined by the subsystem's "wait" setting. You can start and stop processing a datum using the START_PROCESSING and STOP_PROCESSING defines.
ref_search_detailsReturn info about us for reference searching purposes Will be logged as a representation of this datum if it's a part of a search chain
remove_filterRemoves the passed filter, or multiple filters, if supplied with a list.
remove_traitsProc that handles removing multiple traits from a target via a list. Must have a common source and target.
serialize_jsonSerializes into JSON. Does not encode type.
serialize_listReturn a list of data which can be used to investigate the datum, also ensure that you set the semver in the options list
string_assoc_listCaches associative lists with non-numeric stringify-able index keys and stringify-able values (text/typepath -> text/path/number).
string_assoc_nested_listCaches associative nested lists with non-numeric stringify-able index keys and stringify-able values (text/typepath -> text/path/number).
string_numbers_listCaches lists of numeric values.
transition_filter
ui_actpublic
ui_assetspublic
ui_closepublic
ui_datapublic
ui_hostprivate
ui_interactpublic
ui_stateprivate
ui_static_datapublic
ui_statuspublic
update_filtersReapplies all the filters.
update_static_datapublic
update_static_data_for_all_viewerspublic
vv_do_topicThis proc is only called if everything topic-wise is verified. The only verifications that should happen here is things like permission checks! href_list is a reference, modifying it in these procs WILL change the rest of the proc in topic.dm of admin/view_variables! This proc is for "high level" actions like admin heal/set species/etc/etc. The low level debugging things should go in admin/view_variables/topic_basic.dm incase this runtimes.
vv_edit_varCalled when a var is edited with the new value to change to
vv_get_dropdownGets all the dropdown options in the vv menu. When overriding, make sure to call . = ..() first and appent to the result, that way parent items are always at the top and child items are further down. Add seperators by doing VV_DROPDOWN_OPTION("", "---")

Var Details

_active_timers

Active timers with this datum as the target

_datum_components

Components attached to this datum

Lazy associated list in the structure of type -> component/list of components

_listen_lookup

Any datum registered to receive signals from this datum is in this list

Lazy associated list in the structure of signal -> registree/list of registrees

_signal_procs

Lazy associated list in the structure of target -> list(signal -> proctype) that are run when the datum receives that signal

_status_traits

Status traits attached to this datum. associative list of the form: list(trait name (string) = list(source1, source2, source3,...))

datum_flags

Datum level flags

filter_data

List for handling persistent filters.

gc_destroyed

Tick count time when this object was destroyed.

If this is non zero then the object has been garbage collected and is awaiting either a hard del by the GC subsystme, or to be autocollected (if it has no references)

open_uis

Open uis owned by this datum Lazy, since this case is semi rare

tgui_shared_states

global

Associative list of JSON-encoded shared states that were set by tgui clients.

weak_reference

A weak reference to another datum

Proc Details

AddElementTrait

Used to manage (typically non_bespoke) elements with multiple sources through traits so we don't have to make them a components again. The element will be later removed once all trait sources are gone, there's no need of a "RemoveElementTrait" counterpart.

Destroy

Default implementation of clean-up code.

This should be overridden to remove all references pointing to the object being destroyed, if you do override it, make sure to call the parent and return it's return value by default

Return an appropriate QDEL_HINT to modify handling of your deletion; in most cases this is QDEL_HINT_QUEUE.

The base case is responsible for doing the following

Returns QDEL_HINT_QUEUE

GenerateTag

Generate a tag for this /datum, if it implements one Should be called as early as possible, best would be in New, to avoid weakref mistargets Really just don't use this, you don't need it, global lists will do just fine MOST of the time We really only use it for mobs to make id'ing people easier

GetComponent

Return any component assigned to this datum of the given type

This will throw an error if it's possible to have more than one component of that type on the parent

Arguments:

GetComponents

Get all components of a given type that are attached to this datum

Arguments:

GetExactComponent

Return any component assigned to this datum of the exact given type

This will throw an error if it's possible to have more than one component of that type on the parent

Arguments:

RegisterSignal

Register to listen for a signal from the passed in target

This sets up a listening relationship such that when the target object emits a signal the source datum this proc is called upon, will receive a callback to the given proctype Use PROC_REF(procname), TYPE_PROC_REF(type,procname) or GLOBAL_PROC_REF(procname) macros to validate the passed in proc at compile time. PROC_REF for procs defined on current type or it's ancestors, TYPE_PROC_REF for procs defined on unrelated type and GLOBAL_PROC_REF for global procs. Return values from procs registered must be a bitfield

Arguments:

RegisterSignals

Registers multiple signals to the same proc.

RemoveComponentSource

Removes a component source from this datum

TakeComponent

Transfer this component to another parent

Component is taken from source datum

Arguments:

Topic

Called when a href for this datum is clicked

Sends a COMSIG_TOPIC signal

TransferComponents

Transfer all components to target

All components from source datum are taken

Arguments:

UnregisterSignal

Stop listening to a given signal from target

Breaks the relationship between target and source datum, removing the callback when the signal fires

Doesn't care if a registration exists or not

Arguments:

_AddComponent

Creates an instance of new_type in the datum and attaches to it as parent

Sends the COMSIG_COMPONENT_ADDED signal to the datum

Returns the component that was created. Or the old component in a dupe situation where COMPONENT_DUPE_UNIQUE was set

If this tries to add a component to an incompatible type, the component will be deleted and the result will be null. This is very unperformant, try not to do it

Properly handles duplicate situations based on the dupe_mode var

_AddElement

Finds the singleton for the element type given and attaches it to src

_LoadComponent

Get existing component of type, or create it and return a reference to it

Use this if the item needs to exist at the time of this call, but may not have been created before now

Arguments:

_RemoveElement

Finds the singleton for the element type given and detaches it from src You only need additional arguments beyond the type if you're using ELEMENT_BESPOKE

_SendSignal

Internal proc to handle most all of the signaling procedure

Will runtime if used on datums with an empty lookup list

Use the SEND_SIGNAL define instead

_clear_signal_refs

Only override this if you know what you're doing. You do not know what you're doing This is a threat

add_filter

add_traits

Proc that handles adding multiple traits to a target via a list. Must have a common source and target.

change_filter_priority

Updates the priority of the passed filter key

deserialize_json

Deserializes from JSON. Does not parse type.

deserialize_list

Accepts a LIST from deserialize_datum. Should return whether or not the deserialization was successful.

dump_harddel_info

Return text from this proc to provide extra context to hard deletes that happen to it Optional, you should use this for cases where replication is difficult and extra context is required Can be called more then once per object, use harddel_deets_dumped to avoid duplicate calls (I am so sorry)

get_filter

Returns the filter associated with the passed key

get_filter_index

Returns the indice in filters of the given filter name. If it is not found, returns null.

jatum_new_arglist

Gets the flat list that can be passed in a new /type(argslist(retval)) expression to recreate the datum. Must only return a list containing values that can be JATUM serialized

modify_filter

process

This proc is called on a datum on every "cycle" if it is being processed by a subsystem. The time between each cycle is determined by the subsystem's "wait" setting. You can start and stop processing a datum using the START_PROCESSING and STOP_PROCESSING defines.

Since the wait setting of a subsystem can be changed at any time, it is important that any rate-of-change that you implement in this proc is multiplied by the seconds_per_tick that is sent as a parameter, Additionally, any "prob" you use in this proc should instead use the SPT_PROB define to make sure that the final probability per second stays the same even if the subsystem's wait is altered. Examples where this must be considered:

If you override this do not call parent, as it will return PROCESS_KILL. This is done to prevent objects that dont override process() from staying in the processing list

ref_search_details

Return info about us for reference searching purposes Will be logged as a representation of this datum if it's a part of a search chain

remove_filter

Removes the passed filter, or multiple filters, if supplied with a list.

remove_traits

Proc that handles removing multiple traits from a target via a list. Must have a common source and target.

serialize_json

Serializes into JSON. Does not encode type.

serialize_list

Return a list of data which can be used to investigate the datum, also ensure that you set the semver in the options list

string_assoc_list

Caches associative lists with non-numeric stringify-able index keys and stringify-able values (text/typepath -> text/path/number).

string_assoc_nested_list

Caches associative nested lists with non-numeric stringify-able index keys and stringify-able values (text/typepath -> text/path/number).

string_numbers_list

Caches lists of numeric values.

transition_filter

ui_act

public

Called on a UI when the UI receieves a href. Think of this as Topic().

required action string The action/button that has been invoked by the user. required params list A list of parameters attached to the button.

return bool If the user's input has been handled and the UI should update.

ui_assets

public

Called on an object when a tgui object is being created, allowing you to push various assets to tgui, for examples spritesheets.

return list List of asset datums or file paths.

ui_close

public

Called on a UI's object when the UI is closed, not to be confused with client/verb/uiclose(), which closes the ui window

ui_data

public

Data to be sent to the UI. This must be implemented for a UI to work.

required user mob The mob interacting with the UI.

return list Data to be sent to the UI.

ui_host

private

The UI's host object (usually src_object). This allows modules/datums to have the UI attached to them, and be a part of another object.

ui_interact

public

Used to open and update UIs. If this proc is not implemented properly, the UI will not update correctly.

required user mob The mob who opened/is using the UI. optional ui datum/tgui The UI to be updated, if it exists.

ui_state

private

The UI's state controller to be used for created uis This is a proc over a var for memory reasons

ui_static_data

public

Static Data to be sent to the UI.

Static data differs from normal data in that it's large data that should be sent infrequently. This is implemented optionally for heavy uis that would be sending a lot of redundant data frequently. Gets squished into one object on the frontend side, but the static part is cached.

required user mob The mob interacting with the UI.

return list Statuic Data to be sent to the UI.

ui_status

public

Checks the UI state for a mob.

required user mob The mob who opened/is using the UI. required state datum/ui_state The state to check.

return UI_state The state of the UI.

update_filters

Reapplies all the filters.

update_static_data

public

Forces an update on static data. Should be done manually whenever something happens to change static data.

required user the mob currently interacting with the ui optional ui ui to be updated

update_static_data_for_all_viewers

public

Will force an update on static data for all viewers. Should be done manually whenever something happens to change static data.

vv_do_topic

This proc is only called if everything topic-wise is verified. The only verifications that should happen here is things like permission checks! href_list is a reference, modifying it in these procs WILL change the rest of the proc in topic.dm of admin/view_variables! This proc is for "high level" actions like admin heal/set species/etc/etc. The low level debugging things should go in admin/view_variables/topic_basic.dm incase this runtimes.

vv_edit_var

Called when a var is edited with the new value to change to

vv_get_dropdown

Gets all the dropdown options in the vv menu. When overriding, make sure to call . = ..() first and appent to the result, that way parent items are always at the top and child items are further down. Add seperators by doing VV_DROPDOWN_OPTION("", "---")