Keen:New Component Modding Guide

Hello engineers,

With 0.4.14 we introduce a multitude of new entity components, as well as an upgrade to the subpart animation system to be more generic and easy to use.

New Entity Components

MyEntityFXComponent

The Entity FX component provides light, particle and sound effects to a block. See Data/CubeBlocks/Props/TorchStand.sbc for an example.

  <Definition xsi:type="MyObjectBuilder_EntityFXComponentDefinition">
    <Id>
      <TypeId>MyObjectBuilder_EntityFXComponent</TypeId>
      <SubtypeId>TorchStand</SubtypeId>
    </Id>
    <Effects>
      <Effect StartEvent="On" StopEvent="Off" Dummy="detector_fire">
        <EffectId Type="MyObjectBuilder_EffectDefinition" Subtype="Torch"/>
      </Effect>
    </Effects>
  </Definition>

The Effects contains a list of effects, as well as which events toggles them on and off and which dummy they respond to. Finally, they refer to the effect as defined in Data/FX/Effects.sbc.

MotionEventsComponent

The MotionEventsComponent is a simple component that can fire events on the entity depending on how fast it is moving. Look at Data/CubeBlocks/Miscellaneous/Projectiles.sbc for an example.

  <Definition xsi:type="MyObjectBuilder_MotionEventsComponentDefinition">
    <Id Type="MyObjectBuilder_MotionEventsComponent" Subtype="CatapultProjectile"/>
    <VelocityEvent Speed="20" Threshold="Below" Name="MovingSlow"/>
    <VelocityEvent Speed="20" Threshold="Above" Name="MovingFast"/>
  </Definition>

Each velocity event checks if the speed goes from either above to below a speed, or from below to above a speed, and then fires the event in Name on the object.

MyCraftingComponentBlock

The CraftingComponentBlock component adds crafting functionality to a block that relies on the presence of fuel. This is used for the bonfire and the furnace. See Data/CubeBlocks/Production/Bonfire.sbc for an example.

  <Definition xsi:type="MyObjectBuilder_CraftingComponentBlockDefinition">
    <Id>
      <TypeId>MyObjectBuilder_CraftingComponentBlock</TypeId>
      <SubtypeId>BonFire</SubtypeId>
    </Id>
    <AvailableBlueprintClasses>Meals</AvailableBlueprintClasses>
    <AcceptedOperatingItems>
      <OperatingItem Type="MyObjectBuilder_Component" Subtype="ScrapWood"/>
      <OperatingItem Type="MyObjectBuilder_Component" Subtype="ScrapWoodBranches"/>
      <OperatingItem Type="MyObjectBuilder_Component" Subtype="WoodenSticks"/>
    </AcceptedOperatingItems>
  </Definition>

The AcceptedOperatingItems lists which items are accepted as fuel, and AvailableBlueprintClasses lists the category of blueprints it is able to craft.

StockpileComponent

The StockpileComponent component adds the ability to display the inventory items in the world on to the entity per subpart points. This component requires the CubeBlockSubpartComponent to be present. Look at Data/CubeBlocks/Storage/WoodenShelf.sbc for an example.

  <Definition xsi:type="MyObjectBuilder_StockpileComponentDefinition">
    <Id>
      <TypeId>MyObjectBuilder_StockpileComponent</TypeId>
      <SubtypeId>WoodenShelf</SubtypeId>
    </Id>
    <SubpartNameFormat>Inventory_Slot_{0:00}</SubpartNameFormat>
    <MaxNumberOfSubparts>3</MaxNumberOfSubparts>
  </Definition>

The SubpartNameFormat specifies the numerated subpart names that are used for the system, and MaxNumberOfSubparts specifies the limit of visible subparts to try and assign contents to.

CrankComponent

The CrankComponent simply specifies the sound and angular speed and torque properties of a handcrank object. Look at Data/CubeBlocks/Mechanical/TurnWheel.sbc for an example.

  <Definition xsi:type="MyObjectBuilder_CrankComponentDefinition">
    <Id>
      <TypeId>CrankComponent</TypeId>
      <SubtypeId>TurnCrossSmall</SubtypeId>
    </Id>
    <AngularImpulse>25</AngularImpulse>
    <AngularVelocityLimit>4</AngularVelocityLimit>
    <ActionSound>GearWheel</ActionSound>
  </Definition>

AngularImpulse specifies the physical strength of the rotation, AngularVelocityLimit limits the rotation speed and ActionSound specifies the sound played while rotating.

LockableRopeComponent

The LockableRopeComponent specifies the lockable rope drum properties for when you want to make an object that behaves exactly like the lockable rope drum. Look at Data/CubeBlocks/Mechanical/RopeDrum.sbc for an example.

  <Definition xsi:type="MyObjectBuilder_LockableRopeComponentDefinition">
    <Id>
      <TypeId>MyObjectBuilder_LockableRopeComponent</TypeId>
      <SubtypeId>LockableDrumSmall</SubtypeId>
    </Id>
    <MinRopeLength>0.7</MinRopeLength>
    <MaxRopeLength>70</MaxRopeLength>
    <DefaultMaxRopeLength>40</DefaultMaxRopeLength>
  </Definition>

MinRopeLength and MaxRopeLength specify how long a rope can be, and DefaultMaxRopeLength specifies the default rope length when the drum is fully unwinded.

TorsionSpringComponent

The TorsionSpringComponent component specifies torsion spring properties. Look at Data/CubeBlocks/Mechanical/TorsionSpring.sbc for an example.

  <Definition xsi:type="MyObjectBuilder_TorsionSpringComponentDefinition">
    <Id Type="MyObjectBuilder_TorsionSpringComponent" Subtype="RopePowerSmallCogWheel1"/>
    <MaxAngularImpulse>800</MaxAngularImpulse>
    <MaxAngle>135</MaxAngle>
    <MaxFrictionTorque>30</MaxFrictionTorque>
  </Definition>

MaxAngularImpulse specifies the maximum strength the block can provide, the MaxAngle is the maximum angle it rotates and MaxFrictionTorque is the maximum torque friction.

New event system

We changed the way the components interact with each other. This system provides a more elegant approach to handling events so that we do not need as many entity components to create specific effects without requiring programming.

Some examples exist in the definitions, for example, the CatapultProjectile, in Data/CubeBlocks/Miscellaneous/Projectiles.sbc. The MotionEvent component generates some events, and the EntityFXComponent listens to these events and plays an effect.

More components will be converted to integrate with this system in the future to allow, for example, the crafting blocks to trigger animations. This way you can see the SpinningWheel spin while it’s being operated, etc.