HandItem Definition

HomeModdingReferenceSBCHandItemsHandItem Def

Overview

Inherits

• DefinitionBase

This is extended by some Other Definitions.

Requires an xsi:type attribute:

<HandItem xsi:type="MyObjectBuilder_HandItemDefinition">

Directly used only by AutomaticRifleGun, and inherited by other hand tools.

Basics

 ↑   🔗 

PhysicalItemId <PhysicalItemId>	Type: SerializableDefinitionId	Default: (invalid)
The Id of an item (PhysicalItems.sbc). The typeId used by vanilla ones is PhysicalGunObject, it is unknown if other types work or cause problems. Example: <PhysicalItemId Type="PhysicalGunObject" Subtype="WelderItem" /> Has the same syntax as <Id> but different element name of course.
MuzzlePosition <MuzzlePosition>	Type: Vector3	Default: X:0 Y:0 Z:0
Depends on the hand item: AutomaticRifleGun: this is the fallback projectile muzzle position if there's muzzle_projectile dummies in the model. Tools: determines where the aiming logic, particle and light effects originate.
ToolMaterial <ToolMaterial>	Type: String	Default: Grinder
SubtypeId of a PhysicalMaterial Definition (PhysicalMaterials.sbc). Visit Collision Effects for more details on what it's used for in general. Uses the contact properties from the material against the hit object's material. However, only the following tools use it: Grinder: uses particle and sound (not mass-based). Drill: uses only particle, the material for sound is defined in <ToolSounds>'s Soundset subtype.
ToolSounds <ToolSounds>	Type: List<ToolSound>	Default: null
Optional list of sounds, used only by hand tools. Each <ToolSound> can contain: type type (attribute) Type: string Default: null It's expected to be Main</code in all cases. subtype subtype (attribute) Type: string Default: null Depending on the tool this controls different sounds: Grinder: This set to Idle sets the sound played when holding down the primary attack. Welder: This set to Weld sets the sound played when holding down the primary attack. This set to Flame sets the sound played when holding down the secondary attack. Drill: This set to Idle sets the sound played when drilling without hitting anything. This set to Soundset expects sound to be set to a physical material's SubtypeId, which then uses the sound from the contact properties when hitting said material with the drill attack. sound sound (attribute) Type: string Default: null SubtypeId (without Arc or Real prefix) of an audio definition (Audio_*.sbc). except for a certain subtype, see above. Example: <ToolSounds> <ToolSound type="Main" subtype="Weld" sound="ToolPlayWeldMetal" /> <ToolSound type="Main" subtype="Flame" sound="ToolPlayWeldIdle" /> <!-- ... --> </ToolSounds>

Handling

 ↑   🔗 

ScatterSpeed <ScatterSpeed>	Type: Single	Default: 0
Item model is randomly jiggled while shooting, this affects how frequently it changes directions. This animation is disabled if set to 0 or lower.
ShootScatter <ShootScatter>	Type: Vector3	Default: X:0 Y:0 Z:0
The jiggle direction magnitudes. Usage: <ShootScatter> <X>0.0</X> <Y>0.0</Y> <Z>0.0</Z> </ShootScatter> X/Y/Z are Right/Up/Back for positive values, and they're in meters.

Movement

 ↑   🔗 

AimingSpeedMultiplier <AimingSpeedMultiplier>	Type: Single	Default: 1
Holder's movement speed while aiming down sights. Multiplicative with the other movment types.
SprintSpeedMultiplier <SprintSpeedMultiplier>	Type: Single	Default: 1
Holder's forward sprinting speed multiplier.
RunSpeedMultiplier <RunSpeedMultiplier>	Type: Single	Default: 1
Holder's forward jogging speed multiplier.
BackrunSpeedMultiplier <BackrunSpeedMultiplier>	Type: Single	Default: 1
Holder's backwards jogging speed multiplier.
RunStrafingSpeedMultiplier <RunStrafingSpeedMultiplier>	Type: Single	Default: 1
Holder's sideways jogging speed multiplier.
WalkSpeedMultiplier <WalkSpeedMultiplier>	Type: Single	Default: 1
Holder's forward walking speed multiplier.
BackwalkSpeedMultiplier <BackwalkSpeedMultiplier>	Type: Single	Default: 1
Holder's backwards walking speed multiplier.
WalkStrafingSpeedMultiplier <WalkStrafingSpeedMultiplier>	Type: Single	Default: 1
Holder's sideways walking speed multiplier.
CrouchWalkSpeedMultiplier <CrouchWalkSpeedMultiplier>	Type: Single	Default: 1
Holder's forward crouching speed multiplier.
CrouchBackwalkSpeedMultiplier <CrouchBackwalkSpeedMultiplier>	Type: Single	Default: 1
Holder's backwards crouching speed multiplier.
CrouchStrafingSpeedMultiplier <CrouchStrafingSpeedMultiplier>	Type: Single	Default: 1
Holder's sideways crouching speed multiplier.

Lights

 ↑   🔗 

LightColor <LightColor>	Type: Vector4	Default: X:0 Y:0 Z:0 W:0
Usage: <LightColor> <X>0.5</X> <Y>0.2</Y> <Z>1.0</Z> <W>0.25</W> </LightColor> Where X/Y/Z/W = Red/Green/Blue/Alpha.
LightRadius <LightRadius>	Type: Single	Default: 0
Light radius in meters.
LightFalloff <LightFalloff>	Type: Single	Default: 0
Affects how light fades out from its source towards its max radius. 1 is linear, 2 is quadratic, can be anywhere in-between or beyond too.
LightIntensityLower <LightIntensityLower>	Type: Single	Default: 0
Light intensity is randomly picked between this and <LightIntensityUpper>, every update (60 times a second).
LightIntensityUpper <LightIntensityUpper>	Type: Single	Default: 0
See <LightIntensityLower>.
LightGlareSize <LightGlareSize>	Type: Single	Default: 0
Size multiplier to the <Flare>, also multiplied by the randomly picked light intensity.
LightGlareIntensity <LightGlareIntensity>	Type: Single	Default: 1
Intensity multiplier to the <Flare>, also multiplied by the randomly picked light intensity.

Animation

 ↑   🔗 

WeaponType <WeaponType>	Type: MyItemWeaponType	Default: None
When equipped, the value of this (forced lowercase) is set as a variable in the AnimationController, its value will be 1 when equipped and 0 when unequipped. Available values: None Rifle Pistol RocketLauncher
ItemPositioning <ItemPositioning>	Type: MyItemPositioningEnum	Default: TransformFromData
What data to use for the position of the item: TransformFromData - uses the SBC values TransformFromAnim - uses the animation (AnimationController)
ItemPositioning3rd <ItemPositioning3rd>	Type: MyItemPositioningEnum	Default: TransformFromData
Same as <ItemPositioning> but when seen from the outside.
ItemPositioningIronsight <ItemPositioningIronsight>	Type: MyItemPositioningEnum	Default: TransformFromData
Same as <ItemPositioning> but when aiming down sights.
ItemPositioningIronsight3rd <ItemPositioningIronsight3rd>	Type: MyItemPositioningEnum	Default: TransformFromData
Same as <ItemPositioningIronsight> but when seen from the outside.
ItemPositioningShoot <ItemPositioningShoot>	Type: MyItemPositioningEnum	Default: TransformFromData
Same as <ItemPositioning> but when using the item.
ItemPositioningShoot3rd <ItemPositioningShoot3rd>	Type: MyItemPositioningEnum	Default: TransformFromData
Same as <ItemPositioningShoot> but when seen from the outside.
ItemPositioningWalk <ItemPositioningWalk>	Type: MyItemPositioningEnum	Default: TransformFromData
Same as <ItemPositioning> but while moving.
ItemPositioningWalk3rd <ItemPositioningWalk3rd>	Type: MyItemPositioningEnum	Default: TransformFromData
Same as <ItemPositioningWalk> but when seen from the outside.
ItemPosition <ItemPosition>	Type: Vector3	Default: X:0 Y:0 Z:0
Position of the hand item. Usage: <ItemPosition> <X>0.0</X> <Y>0.0</Y> <Z>0.0</Z> </ItemPosition> X/Y/Z are Right/Up/Back for positive values, and they're in meters.
ItemOrientation <ItemOrientation>	Type: Quaternion	Default: X:0 Y:0 Z:0 W:1
Orientation of the hand item. Usage: <ItemOrientation> <X>0.0</X> <Y>0.0</Y> <Z>0.0</Z> <W>1.0</W> </ItemOrientation> You can use quaternions.online (or any other calculator) to get the 4 values from 3 euler angles, but mind that X and Z are flipped (X is roll there, Z is roll in SE).
ItemPosition3rd <ItemPosition3rd>	Type: Vector3	Default: X:0 Y:0 Z:0
Same as <ItemPosition> but when seen from the outside.
ItemOrientation3rd <ItemOrientation3rd>	Type: Quaternion	Default: X:0 Y:0 Z:0 W:1
Same as <ItemOrientation> but when seen from the outside.
ItemWalkingPosition <ItemWalkingPosition>	Type: Vector3	Default: X:0 Y:0 Z:0
Same as <ItemPosition> but while walking.
ItemWalkingOrientation <ItemWalkingOrientation>	Type: Quaternion	Default: X:0 Y:0 Z:0 W:1
Same as <ItemOrientation> but while walking.
ItemWalkingPosition3rd <ItemWalkingPosition3rd>	Type: Vector3	Default: X:0 Y:0 Z:0
Same as <ItemWalkingPosition> but when seen from the outside.
ItemWalkingOrientation3rd <ItemWalkingOrientation3rd>	Type: Quaternion	Default: X:0 Y:0 Z:0 W:1
Same as <ItemWalkingOrientation> but when seen from the outside.
ItemIronsightPosition <ItemIronsightPosition>	Type: Vector3	Default: X:0 Y:0 Z:0
Same as <ItemPosition> but while aiming down sights.
ItemIronsightOrientation <ItemIronsightOrientation>	Type: Quaternion	Default: X:0 Y:0 Z:0 W:1
Same as <ItemOrientation> but while aiming down sights.
ItemShootPosition <ItemShootPosition>	Type: Vector3	Default: X:0 Y:0 Z:0
Same as <ItemPosition> but while shooting or using the tool.
ItemShootOrientation <ItemShootOrientation>	Type: Quaternion	Default: X:0 Y:0 Z:0 W:1
Same as <ItemOrientation> but while shooting or using the tool.
ItemShootPosition3rd <ItemShootPosition3rd>	Type: Vector3	Default: X:0 Y:0 Z:0
Same as <ItemShootPosition> but when seen from the outside.
ItemShootOrientation3rd <ItemShootOrientation3rd>	Type: Quaternion	Default: X:0 Y:0 Z:0 W:1
Same as <ItemShootOrientation> but when seen from the outside.
FingersAnimation <FingersAnimation>	Type: String	Default: null
Optional. Forced lowercase and sent to the AnimationController as an animation event, right after this definition's subtypeId (also forced lowercase).
RightHandPosition <RightHandPosition>	Type: Vector3	Default: X:0 Y:0 Z:0
RightHandOrientation <RightHandOrientation>	Type: Quaternion	Default: X:0 Y:0 Z:0 W:1
SimulateRightHandFps <SimulateRightHandFps>	Type: Nullable<Boolean>	Default: null
Whether the right hand is free to drift using inverse-kinematics, used when controlling the character and in first person view. If undefined or set to null, it will use <SimulateRightHand>'s value.
SimulateRightHand <SimulateRightHand>	Type: Boolean	Default: True
Whether the right hand is free to drift using inverse-kinematics, used when character is seen from the outside (by yourself or others).
LeftHandPosition <LeftHandPosition>	Type: Vector3	Default: X:0 Y:0 Z:0
LeftHandOrientation <LeftHandOrientation>	Type: Quaternion	Default: X:0 Y:0 Z:0 W:1
SimulateLeftHandFps <SimulateLeftHandFps>	Type: Nullable<Boolean>	Default: null
Whether the left hand is free to drift using inverse-kinematics, used when controlling the character and in first person view. If undefined or set to null, it will use <SimulateLeftHand>'s value.
SimulateLeftHand <SimulateLeftHand>	Type: Boolean	Default: True
Whether the left hand is free to drift using inverse-kinematics, used when character is seen from the outside (by yourself or others).

Bobbing

 ↑   🔗 

BlendTime <BlendTime>	Type: Single	Default: 0
ShootBlend <ShootBlend>	Type: Single	Default: 0
Used instead of <BlendTime> while shooting or using the tool.
RunMultiplier <RunMultiplier>	Type: Single	Default: 0
Used only in first person view. Item bobbing multiplier (on all axis) while jogging.
XAmplitudeScale <XAmplitudeScale>	Type: Single	Default: 0
Multiplies the weapon bobbing on this specified axis when viewing in first person.
YAmplitudeScale <YAmplitudeScale>	Type: Single	Default: 0
See <XAmplitudeScale>.
ZAmplitudeScale <ZAmplitudeScale>	Type: Single	Default: 0
See <XAmplitudeScale>.
AmplitudeMultiplier3rd <AmplitudeMultiplier3rd>	Type: Single	Default: 0
Used instead of <XAmplitudeScale> when in 3rd person.
ShakeAmountNoTarget <ShakeAmountNoTarget>	Type: Single	Default: 0
Possibly not used.
ShakeAmountTarget <ShakeAmountTarget>	Type: Single	Default: 0
Possibly not used.

(Top) | From DefinitionBase:

Common

 ↑   🔗 

Id <Id>	Type: SerializableDefinitionId	Default: (invalid)
The type and subtype combined make up a unique identifier for this definition. If two definitions use the same Type+Subtype (Subtypes are only unique per Type), then the last to load will override the first one(s). For more details see Things to know about SBC. TypeId <TypeId> Type: string Default: (invalid) Must be an existing type with or without the "MyObjectBuilder_" prefix. Some types require an xsi:type, refer to the vanilla files for the exact pairing. TypeId vs xsi:type SubtypeId <SubtypeId> Type: string Default: (empty) This can be invented and only needs to be unique per TypeId. Vanilla game re-uses some subtypes over multiple types (e.g. Iron is used for Ore type and Ingot type). An empty value is also a valid subtype (which vanilla also uses on at least 5 blocks). Type Type (attribute) Type: string Default: (invalid) Same behavior as <TypeId>, do not define both. Subtype Subtype (attribute) Type: string Default: (empty) Same behavior as <SubtypeId>, do not define both. Example: <Id> <TypeId>CubeBlock</TypeId> <SubtypeId>FancyTable</SubtypeId> </Id> Because it has attribute alternatives it can also be declared as: <Id Type="CubeBlock" Subtype="FancyTable" />
DisplayName <DisplayName>	Type: String	Default: null
If the object defined here is visible anywhere in the game GUI, this would be the name shown for it. In cases where it is used, it is very much required. Can be plain-text. If the text contains DisplayName_ then: A localization key (from .resx files) will be searched for. It will scan for text variables to replace.
Description <Description>	Type: String	Default: null
Optional. If the object defined here is shown with a description in the game GUI (Hotbar/G-menu, HUD, etc) then this is the place to write it. Can be plain-text. If the text contains Description_ then: A localization key (from .resx files) will be searched for. It will scan for text variables to replace. If the final text (plain, localized or variable-replaced) contains {0}, {1}, etc, then they will replaced by kb&m control binds defined in <DescriptionArgs>.
DescriptionArgs <DescriptionArgs>	Type: String	Default: null
Optional. A comma-separated list of control IDs which are referenced in <Description> by {number} tags, which then get replaced by the keyboard or mouse bind that the viewer has for those controls. Example: <Description>Press {0} to fire, {1} to change color, {2} to interact.</description> <DescriptionArgs>PRIMARY_TOOL_ACTION,CUBE_COLOR_CHANGE,USE</DescriptionArgs> And each player will see their current binds for those actions. The control IDs can be found in your %appdata%/SpaceEngineers/SpaceEngineers.cfg at the ControlsButtons section.
Icon <Icon>	Type: String[]	Default: null
Icon(s) for the definition which may or may not be used depending on the definition type. Path to a .dds or .png file relative to current mod's folder. Falls back to game folder if not found in current mod. Referencing assets in other mods Can be declared multiple times which will stack icons on top of eachother, however it will not work for all definitions. Known definitions to work or not work with multiple icons Working: Blocks, BlockVariantGroups and component items seen in G-menu, BlockInfo (HUD right side) and toolbars; Blueprints in terminal production tab; Blocks and PhysicalItems in gamepad HUD. Partial: Blocks seen in terminal. Not working: HandItems (uses PhysicalItem's icon instead); Blocks and BlockVariantGroups seen in build planner, radial menu and some economy GUIs; PhysicalItems in economy GUIs and stores; Prefabs in stores; BlueprintClass (tabs) in terminal production tab; BankingSystemDefinition (Game\BankingSystem.sbc); Emotes (both kinds of definitions) in gamepad HUD; Block skins; RespawnShips. Special cases: Economy contracts, FactionIcons Definition.
DLC <DLC>	Type: String[]	Default: null
Optional. The DLC subtypeId that this definition will require. For the IDs, refer to <SE>\Content\Data\Game\DLCs.sbc. Can be declared multiple times to require multiple DLCs. Most definition types won't check for this, the ones that do: blocks, emotes and possibly anything else that can be placed in the toolbar.
AvailableInSurvival <AvailableInSurvival>	Type: Boolean	Default: true
Depends on the definition if it uses this, and if it does then this determines whether it can be accessible in survival game mode. Currently known definitions that do use this: Blocks, BlockVariantGroups, BlockCategories and any definition that can show up in a toolbar. EntityStatComponent Definition and EntityStat Definition.
Public <Public>	Type: Boolean	Default: true
If the definition is visible or accessible in some cases. For blocks, this only hides them and they can still be built using projectors and other means.
Enabled Enabled (attribute)	Type: Boolean	Default: true
If set to false it will remove the definition after it's been loaded. Example usage: <Definition Enabled="false"> The "Definition" above is the opening element that for the entire definition, not an inner node like <DisplayName> is. The opening node can have a different name for other definitions, some examples <Component>, <Blueprint>, etc.
xsi:type xsi:type (attribute)	Type: string	Default: null
Name of an object that this definition will be deserialized as. Sometimes required, depends on the definition. The wiki page for any given definition will mention at the top what xsi:type it requires, if any. The game's sbc files are also a reference on what xsi:types are required for a given definition. This attribute is available on all elements and comes from the XML specification. This game relies on this attribute to change which sub-definition object is used to deserialize that element's contents. It's what allows, for example, a thruster to have unique elements (such as <MinPlanetaryInfluence>) that no other block definitions have. For more details on how this relates to the TypeId, and usage examples, see: Things to know about SBC - TypeId vs xsi:type.

Obsolete Elements

 ↑   🔗 

Elements that exist in the game code or vanilla SBC, but do nothing

Note: this list only contains root-level from this definition only, nothing from inherited ones.

<XAmplitudeOffset>	Type: Single	Default: 0
Not used.
<YAmplitudeOffset>	Type: Single	Default: 0
Not used.
<ZAmplitudeOffset>	Type: Single	Default: 0
Not used.

Other Definitions

 ↑   🔗 

Definitions inheriting from this:

• Modding/Reference/SBC/HandItems/HandDrill Definition (transclusion) (← links)
• Modding/Reference/SBC/HandItems/AngleGrinder Definition (transclusion) (← links)
• Modding/Reference/SBC/HandItems/Welder Definition (transclusion) (← links)
• Modding/Reference/SBC/HandItems/EngineerToolBase Definition (transclusion) (← links)

---