hkb_editor.templates.common

Animation dataclass

anim_id property

anim_id: int

The Y part of aXXX_YYYYYY without leading zeros.

category property

category: int

the X part of aXXX_YYYYYY without leading zeros.

CommonActionsMixin

__init__

__init__(behavior: HavokBehavior)

Provides convenience methods for common actions.

Designed as a Mixin so that it can be passed around with a bound behavior (e.g. for template execution).

Parameters:

Name	Type	Description	Default
behavior	HavokBehavior	The behavior the convenience functions will apply to.	required

add_wildcard_state

add_wildcard_state(statemachine: HkbRecord | str, state: HkbRecord | str, event: Event | str = None, transition_effect: HkbRecord | str = None, copy_transition_effect: bool = False, flags: hkbStateMachine_TransitionInfoArray_Flags = 3584) -> HkbRecord

Add a state to a statemachine and setup a wildcard transition for it.

Goes really well with create_state_chain!

Parameters:

Name	Type	Description	Default
statemachine	HkbRecord | str	The statemachine to add the state to.	required
state	HkbRecord | str	The state to add, which should not have been added elsewhere yet. Note that if this is a string a new state with that name will be created.	required
event	Event | str	The wildcard transition event. If None, no wildcard transition will be setup.	None
transition_effect	HkbRecord | str	The transition effect to use for the wildcard transition.	None
copy_transition_effect	bool	If True and a transition effect is provided, a copy of the effect is created with a new name based on the event's name (which is how FS often does it).	False
flags	hkbStateMachine_TransitionInfoArray_Flags	Flags of the transition.	3584

Returns:

Type	Description
HkbRecord	The state that was added to the statemachine.

animation

animation(animation: Animation | str | int, create: bool = True) -> Animation

Get the animation with the specified name, or create a new one if it doesn't exist yet.

Animation names must follow the pattern aXXX_YYYYYY. Animation names are typically associated with one or more CustomManualSelectorGenerators (CMSG). See new_cmsg for details.

TODO mention animations.txt

Parameters:

Name	Type	Description	Default
animation	str	The name of the animation slot following the aXXX_YYYYYY pattern.	required
create	bool	If True create a new variable if it cannot be resolved.	True

Returns:

Type	Description
Animation	The generated animation name. Note that the full name is almost never used.

bind_variable

bind_variable(record: HkbRecord, path: str, variable: Variable | str | int) -> HkbRecord

Bind a record field to a variable.

This allows to control aspects of a behavior object through HKS or TAE. Most commonly used for ManualSelectorGenerators. Note that in HKS variables are referenced by their name, in all other places the variables' indices are used.

If the record does not have a variableBindingSet yet it will be created. If the record already has a binding for the specified path it will be updated to the provided variable.

Parameters:

Name	Type	Description	Default
record	HkbRecord | str	The record which should be bound.	required
path	str	Path to the record's member to bind, with deeper levels separated by /.	required
variable	Variable | str | int	The variable to bind the field to.	required

Returns:

Type	Description
HkbRecord	The variable binding set to which the field was bound.

clear_variable_binding

clear_variable_binding(record: HkbRecord, path: str) -> None

Removes all variable bindings for the specified field path from this record. Will do nothing if the record in question does not (or can not) have a variable binding set.

Parameters:

Name	Type	Description	Default
record	HkbRecord	The record to clear the variable binding set from.	required
path	str	Path to the bound field.	required

copy_attributes

copy_attributes(source: HkbRecord | str, dest: HkbRecord | str, *attributes, allow_type_mismatch: bool = False) -> None

Copy all attributes from the source record to the destination record.

Parameters:

Name	Type	Description	Default
source	HkbRecord | str	The record to read attributes from.	required
dest	HkbRecord | str	The record to write attributes to.	required
allow_type_mismatch	bool	If False, the source and destination record types must match exactly.	False

Raises:

Type	Description
ValueError	If allow_type_mismatch is False and the source and destination record types mismatch.

create_blend_chain

create_blend_chain(animation: Animation | str | int, blend_weight: int = 1, cmsg_name: str = None, *, offsetType: CustomManualSelectorGenerator_OffsetType = CmsgOffsetType.IDLE_CATEGORY, animeEndEventType: CustomManualSelectorGenerator_AnimeEndEventType = AnimeEndEventType.NONE, cmsg_kwargs: dict[str, Any] = None) -> tuple[HkbRecord, HkbRecord, HkbRecord]

Creates another common behavior structure, used for e.g. usable items and gestures: BlenderGeneratorChild -> CMSG -> ClipGenerator.

This setup is typically used with a parametric blend BlenderGenerator, where blend_weight also acts as the ID of the generator. Make sure this ID is an integer and unique within the BlenderGenerator when using this setup!

Parameters:

Name	Type	Description	Default
animation	Animation | str | int	Animation to use for the clip.	required
blend_weight	int	Blend weight of the BlenderGeneratorChild.	1
cmsg_name	str	Name of the CMSG, typically ends with "_CMSG".	None
offsetType	CustomManualSelectorGenerator_OffsetType	Generator selection mode of the CMSG. Usually there's only one clip attached and this doesn't matter.	IDLE_CATEGORY
animeEndEventType	CustomManualSelectorGenerator_AnimeEndEventType	What the CMSG should do once the activated generator finishes.	NONE

Returns:

Type	Description
tuple[HkbRecord, HkbRecord, HkbRecord]	The new hkbBlenderGeneratorChild, CustomManualSelectorGenerator, and hkbClipGenerator records.

create_state_chain

create_state_chain(state_id: int, animation: Animation | str | int, name: str, *, state_kwargs: dict[str, Any] = None, cmsg_kwargs: dict[str, Any] = None, clip_kwargs: dict[str, Any] = None) -> tuple[HkbRecord, HkbRecord, HkbRecord]

Creates one of the most common behavior structures in recent FromSoft titles: StateInfo -> CMSG -> ClipGenerator.

Note that this chain will not be attached. You still have to append it to a statemachine's states (see TemplateContext.array_add) and setup a transition (e.g. using register_wildcard_transition).

Parameters:

Name	Type	Description	Default
state_id	int	ID of the generated StateInfo.	required
animation	Animation | str | int	The animation to play.	required
name	str	A name to base the new objects' names on.	required
state_kwargs	dict[str, Any]	Additional attributes for the generated StateInfo.	None
cmsg_kwargs	dict[str, Any]	Additional attributes for the generated CMSG.	None
clip_kwargs	dict[str, Any]	Additional attributes for the generated ClipGenerator.	None

Returns:

Type	Description
tuple[HkbRecord, HkbRecord, HkbRecord]	The new hkbStateInfo, CustomManualSelectorGenerator and hkbClipGenerator records.

event

event(event: Event | str | int, *, create: bool = True) -> Event

Get the event with the specified name, or create it if it doesn't exist yet.

Events are typically used to trigger transitions between statemachine states. See get_next_state_id for details. TODO mention events.txt

Parameters:

Name	Type	Description	Default
event	str	The name of the event to create. Typically starts with W_.	required
create	bool	If True create a new variable if it cannot be resolved.	True

Returns:

Type	Description
Event	The generated event.

find_array_item

find_array_item(array: HkbArray, **conditions) -> HkbRecord

Find an item in an array with specific attributes. If it's an array of pointers they will be resolved to their target objects automatically.

Parameters:

Name	Type	Description	Default
array	HkbArray	The array to search	required
conditions	dict[str, Any]	Only return items whose fields have the specified values.	{}

Raises:

Type	Description
AttributeError	If the array items do not have any of the specified fields.

Returns:

Type	Description
HkbRecord	The first item in the array matching the conditions, or None if no items match.

get_default_transition_effect

get_default_transition_effect() -> HkbRecord

Returns the most commonly linked CustomTransitionEffect. In Elden Ring and Nightreign this object will be called DefaultTransition.

Note that for very small behaviors like enemies this may not return what you expect. If in doubt use TemplateContext.find instead.

Returns:

Type	Description
HkbRecord	The most common transition effect object.

get_next_state_id

get_next_state_id(statemachine: HkbRecord) -> int

Find the next state ID which is 1 higher than the highest one in use.

Parameters:

Name	Type	Description	Default
statemachine	HkbRecord	The statemachine to search.	required

Returns:

Type	Description
int	The next free state ID.

make_copy

make_copy(source: HkbRecord | str, *, object_id: str = '<new>', **overrides) -> HkbRecord

Creates a copy of a record.

Parameters:

Name	Type	Description	Default
source	HkbRecord | str	The record to copy.	required
object_id	str	The object ID the record should use. Create a new ID if "" is passed.	'<new>'
overrides	dict[str, Any]	Values to change in the copy before returning it.	{}

Returns:

Type	Description
HkbRecord	A copy of the source altered according to the specified overrides.

new_blender_generator

new_blender_generator(children: list[HkbRecord | str], *, object_id: str = '<new>', name: str = '', blendParameter: float = 1.0, minCyclicBlendParameter: float = 0.0, maxCyclicBlendParameter: float = 1.0, indexOfSyncMasterChild: int = -1, **kwargs) -> HkbRecord

Generator object for handling animation blending (transitioning from one animation to another).

Parameters:

Name	Type	Description	Default
children	list[HkbRecord | str]	Blending children, see new_blender_generator_child.	required
object_id	str	The object ID the record should use. Create a new ID if "" is passed.	'<new>'
name	str	The name of the new object.	''
blendParameter	float	How far the blending has progressed. Typically bound to a variable and controlled from HKS or TAE.	1.0
minCyclicBlendParameter	float	?unknown?	0.0
maxCyclicBlendParameter	float	?unknown?	1.0
indexOfSyncMasterChild	int	?unknown?	-1

Returns:

Type	Description
HkbRecord	The new hkbBlenderGenerator record.

new_blender_generator_child

new_blender_generator_child(generator: HkbRecord | str, *, object_id: str = '<new>', weight: float = 1.0, worldFromModelWeight: int = 1, **kwargs) -> HkbRecord

A child object that can be attached to a BlenderGenerator (new_blender_generator).

Parameters:

Name	Type	Description	Default
generator	HkbRecord | str	The generator to activate as this blend layer is weighted more.	required
object_id	str	The object ID the record should use. Create a new ID if "" is passed.	'<new>'
weight	float	Weight of this blend layer compared to siblings.	1.0
worldFromModelWeight	int	?unknown?	1

Returns:

Type	Description
HkbRecord	The new hkbBlenderGeneratorChild record.

new_clip

new_clip(animation: Animation | str | int, *, object_id: str = '<new>', name: str = None, playbackSpeed: int = 1, mode: hkbClipGenerator_PlaybackMode = PlaybackMode.SINGLE_PLAY, **kwargs) -> HkbRecord

Create a new ClipGenerator. These nodes are responsible for running TAE animations.

Parameters:

Name	Type	Description	Default
animation	Animation | str | int	The animation to execute.	required
object_id	str	The object ID the record should use. Create a new ID if "" is passed.	'<new>'
name	str	The name of the new object.	None
playbackSpeed	int	Multiplicative factor for the animation's playback speed.	1
mode	hkbClipGenerator_PlaybackMode	How to play the animation.	SINGLE_PLAY
kwargs	dict	Additional attributes for the record.	{}

Returns:

Type	Description
HkbRecord	The new hkbClipGenerator record.

new_cmsg

new_cmsg(animId: int | Animation, *, object_id: str = '<new>', name: str = '', generators: list[HkbRecord | str] = None, enableScript: bool = True, enableTae: bool = True, offsetType: CustomManualSelectorGenerator_OffsetType = CmsgOffsetType.NONE, animeEndEventType: CustomManualSelectorGenerator_AnimeEndEventType = AnimeEndEventType.FIRE_NEXT_STATE_EVENT, changeTypeOfSelectedIndexAfterActivate: CustomManualSelectorGenerator_ChangeTypeOfSelectedIndexAfterActivate = ChangeIndexType.NONE, checkAnimEndSlotNo: int = -1, rideSync: CustomManualSelectorGenerator_RideSync = RideSync.DISABLE, isBasePoseAnim: bool = True, **kwargs) -> HkbRecord

Create a new CustomManualSelectorGenerator (CMSG). A CMSG selects the generator to activate based on the state of the character, e.g. equipped skill, magic, or idle stance.

Parameters:

Name	Type	Description	Default
animId	int | Animation	ID of animations this CMSG will handle (the Y part of aXXX_YYYYYY). All attached ClipGenerators should use this animation ID.	required
object_id	str	The object ID the record should use. Create a new ID if "" is passed.	'<new>'
name	str	The name of the new object.	''
generators	list[HkbRecord | str]	The generators this CMSG may choose from.	None
enableScript	bool	?unknown?	True
enableTae	bool	Does this CMSG have actual animations associated?	True
offsetType	CustomManualSelectorGenerator_OffsetType	How to choose the generator index to activate.	NONE
animeEndEventType	CustomManualSelectorGenerator_AnimeEndEventType	What to do once the activated generator finishes.	FIRE_NEXT_STATE_EVENT
changeTypeOfSelectedIndexAfterActivate	CustomManualSelectorGenerator_ChangeTypeOfSelectedIndexAfterActivate	What to do when the generator index changes while already active.	NONE
checkAnimEndSlotNo	int	?unknown?	-1
rideSync	CustomManualSelectorGenerator_RideSync	Related to torrent, only present in Elden Ring.	DISABLE
isBasePoseAnim	bool	Related to nightfarer animation layers, only present in Nightreign.	True
kwargs	dict	Additional attributes for the record.	{}

Returns:

Type	Description
HkbRecord	The created CMSG record.

new_layer_generator

new_layer_generator(*, object_id: str = '<new>', name: str = '', layers: list[HkbRecord | str] = None, indexOfSyncMasterChild: int = -1, flags: hkbLayerGenerator_Flags = LayerGeneratorFlags.NONE, **kwargs) -> HkbRecord

Generator object for playing multiple animations at the same time (e.g. half blends).

Parameters:

Name	Type	Description	Default
object_id	str	The object ID the record should use. Create a new ID if "" is passed.	'<new>'
name	str	The name of the new object.	''
layers	list[HkbRecord | str]	Animation layers to activate. See new_layer_generator_child.	None
indexOfSyncMasterChild	int	The child to use for synchronizing durations if SYNC is true.	-1
flags	hkbLayerGenerator_Flags	Additional flags for this generator.	NONE

Returns:

Type	Description
HkbRecord	The new hkbLayerGenerator record.

new_layer_generator_child

new_layer_generator_child(*, object_id: str = '<new>', generator: HkbRecord | str = None, boneWeights: HkbRecord | str = None, useMotion: bool = False, weight: float = 0.5, fadeInDuration: float = 0.0, fadeOutDuration: float = 0.0, onEventId: Event | str | int = -1, offEventId: Event | str | int = -1, onByDefault: bool = False, fadeInOutCurve: hkbBlendCurveUtils_BlendCurve = BlendCurve.SMOOTH, **kwargs) -> HkbRecord

Creates a new animation layer. Should be attached to a LayerGenerator, see new_layer_generator.

Parameters:

Name	Type	Description	Default
object_id	str	The object ID the record should use. Create a new ID if "" is passed.	'<new>'
generator	HkbRecord | str	The actual animation generator to activate.	None
boneWeights	HkbRecord | str	How much each bone of this animation will affect the end result.	None
useMotion	bool	Set to true if this animation's world transform should be used (worldFromModel). Typically only active for one layer per LayerGenerator.	False
weight	float	How much this layer affects the end result.	0.5
fadeInDuration	float	Time over which this layer gradually becomes activates.	0.0
fadeOutDuration	float	Time over which this layer gradually becomes deactivates.	0.0
onEventId	Event | str | int	An event to switch on this layer.	-1
offEventId	Event | str | int	An event to switch off this layer.	-1
onByDefault	bool	Whether this layer should be active when its parent activates.	False
fadeInOutCurve	hkbBlendCurveUtils_BlendCurve	Curve to use when fading this layer in or out.	SMOOTH

Returns:

Type	Description
HkbRecord	The new hkbLayer record.

new_manual_selector

new_manual_selector(variable: Variable | str | int, *, object_id: str = '<new>', name: str = '', generators: list[HkbRecord | str] = None, selectedGeneratorIndex: int = 0, variableBindingSet: HkbRecord | str = None, generatorChangedTransitionEffect: HkbRecord | str = None, selectedIndexCanChangeAfterActivate: bool = False, **kwargs) -> HkbRecord

Creates a new ManualSelectorGenerator (MSG). The generator to activate is typically controlled by binding the selectedGeneratorIndex to a variable, which is then set from hks using SetVariable().

Parameters:

Name	Type	Description	Default
variable	Variable | str | int	Variable to bind the selectedGeneratorIndex to. Set to None if you don't want to bind it yet.	required
object_id	str	The object ID the record should use. Create a new ID if "" is passed.	'<new>'
name	str	The name of the new object.	''
generators	list[HkbRecord | str]	The generators this MSG may choose from. First generator will be 0.	None
selectedGeneratorIndex	int	Initial value of the selected generator.	0
variableBindingSet	HkbRecord | str	Set this if you want to reuse an already existing variable binding.	None
generatorChangedTransitionEffect	HkbRecord | str	Transition effect to use when the generator index changes while active.	None
selectedIndexCanChangeAfterActivate	bool	Whether the active generator index is allowed to change while active.	False
kwargs	dict	Additional attributes for the record.	{}

Returns:

Type	Description
HkbRecord	The created MSG record.

new_record

new_record(object_type_name: str, object_id: str, **kwargs: Any) -> HkbRecord

Create an arbitrary new hkb object. If an object ID is provided or generated, the object will also be added to the behavior.

Note that when using this method you have to match the expected field type, so helper classes like Variable, Event and Animation cannot be used.

Parameters:

Name	Type	Description	Default
object_type_name	str	The type of the object to generate. In decompiled hkb this is usually the comment under the <object id="..." typeid="..."> line.	required
object_id	str	The object ID the record should use. Create a new ID if "" is passed.	required
kwargs	Any	Any fields you want to set for the generated object. Fields not specified will use their type default (e.g. int will be 0, str will be empty, etc.). You may also specify paths (subrecord/field).	{}

Raises:

Type	Description
KeyError	If kwargs contains any paths not found in the generated object.

Returns:

Type	Description
HkbRecord	The generated object.

new_statemachine_state

new_statemachine_state(stateId: int, *, object_id: str = '<new>', name: str = '', transitions: HkbRecord | str = None, generator: HkbRecord | str = None, probability: float = 1.0, enable: bool = True, **kwargs) -> HkbRecord

Create a new statemachine state.

Every statemachine can have only one state active at a time. However, it is possible to have multiple statemachines active by using layered animations (e.g. blending or half blends, see new_blender_generator and new_layer_generator).

FromSoft usually uses wildcard transitions, i.e. every state can transition to any state within the same statemachine with no prior conditions. However, states may also define dedicated transitions to other states.

Parameters:

Name	Type	Description	Default
stateId	int	ID of the state. State IDs must be unique within their statemachine. See get_next_state_id to generate a new valid ID.	required
object_id	str	The object ID the record should use. Create a new ID if "" is passed.	'<new>'
name	str	The name of the new object.	''
transitions	HkbRecord | str	Custom transitions to other states.	None
generator	HkbRecord | str	The generator this state will activate. Usually a CMSG or MSG, but any type of generator is valid, including a statemachine.	None
probability	float	Probability weight to activate this state when the statemachine chooses a state at random.	1.0
enable	bool	Whether this state can be activated.	True

Returns:

Type	Description
HkbRecord	The new hkbStateMachine::StateInfo record.

new_transition_info

new_transition_info(toStateId: int, eventId: Event | str | int, *, transition: HkbRecord | str = None, flags: hkbStateMachine_TransitionInfoArray_Flags = 0, **kwargs) -> HkbRecord

Defines a transition from the active state to another.

Parameters:

Name	Type	Description	Default
toStateId	int	ID of the state to transition to.	required
eventId	Event | str | int	The event that will activate this transition (if the owning object is active).	required
transition	HkbRecord | str	Blending effect to use when this transition becomes active. Often empty or the default transition (see get_default_transition_effect).	None
flags	hkbStateMachine_TransitionInfoArray_Flags	Additional flags for this transition.	0

Returns:

Type	Description
HkbRecord	The new hkbStateMachine::TransitionInfo record.

new_transition_info_array

new_transition_info_array(*, object_id: str = '<new>', transitions: list[HkbRecord] = None) -> HkbRecord

An object for defining possible transitions to other states within a statemachine.

Parameters:

Name	Type	Description	Default
object_id	str	The object ID the record should use. Create a new ID if "" is passed.	'<new>'
transitions	list[HkbRecord]	List of possible transitions. See new_transition_info to generate these.	None

Returns:

Type	Description
HkbRecord	The new hkbStateMachine::TransitionInfoArray record.

register_wildcard_transition

register_wildcard_transition(statemachine: HkbRecord | str, toStateId: int, eventId: Event | str | int, *, transition_effect: HkbRecord | str = None, flags: hkbStateMachine_TransitionInfoArray_Flags = 3584, **kwargs) -> None

Sets up a wildcard transition for a given statemachine's state, i.e. a way to transition to this state from any other state.

Parameters:

Name	Type	Description	Default
statemachine	HkbRecord | str	The statemachine to setup the wildcard transition for.	required
toStateId	int	ID of the target state.	required
eventId	Event | str | int	Event that activates this transition.	required
transition_effect	HkbRecord | str	Effect to use when this transition activates. If None will use the get_default_transition_effect.	None
flags	hkbStateMachine_TransitionInfoArray_Flags	Additional flags for this transition.	3584

resolve_object

resolve_object(reference: Any, default: Any = None) -> HkbRecord

Safely retrieve the record referenced by the input.

If the input is None or already a HkbRecord, simply retrieve it. If it's the ID of an existing object, resolve it. In all other cases treat it as a query string and return the first matching object.

Parameters:

Name	Type	Description	Default
reference	Any	A reference to a record.	required
default	Any	What to return if the reference can not be resolved.	None

Returns:

Type	Description
HkbRecord	The resolved record or None.

variable

variable(variable: Variable | str | int, *, var_type: hkbVariableInfo_VariableType = VariableType.INT32, range_min: int = 0, range_max: int = 0, default: Any = 0, create: bool = True) -> Variable

Get a variable by name, or create it if it doesn't exist yet.

Variables are typically used to control behaviors from other subsystems like HKS and TAE. See CommonActionsMixin.bind_variable for the most common use case.

Parameters:

Name	Type	Description	Default
variable	str	The name of the variable.	required
var_type	hkbVariableInfo_VariableType	The type of data that will be stored in the variable.	INT32
range_min	int	Minimum allowed value.	0
range_max	int	Maximum allowed value.	0
create	bool	If True create a new variable if it cannot be resolved.	True

Returns:

Type	Description
Variable	Description of the generated variable.