Official Modules

This document describes the configuration of all official block modules.

See Modules for general information about modules.

Steering Module

The steering module allows rotation the block along one axis controlled by user input, similar to the steering block.

Example:

<Modules>
    <Steering>
        <LeftKey key="left" />
        <RightKey key="right" />
        <SpeedSlider key="speed" />
        <AutomaticToggle key="automatic" />

        <Axis>Y</Axis>

        <MaxAngularSpeed>300</MaxAngularSpeed>
        <TargetAngleSpeed>0.8</TargetAngleSpeed>

        <HasLimits>True</HasLimits>

        <LimitsDisplay>
            <Position x="0" y="0" z="0" />
            <Rotation x="0" y="0" z="0" />
            <Scale x="0.5" y="0.5" z="0.5" />
        </LimitsDisplay>
        <LimitsDefaultMin>45</LimitsDefaultMin>
        <LimitsDefaultMax>45</LimitsDefaultMax>
        <LimitsHighestAngle>180</LimitsHighestAngle>
    </Steering>
</Modules>

Explanation of the available elements:

LeftKey, RightKey: Keybindings to control the steering. References to keys that must be defined in the ModuleMapperTypes element.
SpeedSlider: Defines the speed range possible. Reference to a slider that must be defined in the ModuleMapperTypes element.
AutomaticToggle: Toggle to control whether automatic mode is active. Reference to a toggle that must be defined in the ModuleMapperTypes element. If an automatic mode is not desired, just set showInMapper to false on the toggle definition.
Axis: Around which axis the block should rotate. Can be X, Y, or Z.
MaxAngularSpeed: Limits how fast the block's Rigidbody can possibly rotate. See Rigidbody.maxAngularVelocity in the Unity documentation for more information.
TargetAngleSpeed: Constant speed multiplier.
HasLimits: Whether limits can be used with the block. The following elements are required if HasLimits is True, but are not necessary if HasLimits is False:
- LimitsDisplay: A copy of the block's visuals is shown in the block mapper for the limits display. This defines how it's shown.
- LimitsDefaultMin, LimitsDefaultMax: Default values for the limits.
- LimitsHighestAngle: The highest angle a limit can be set to.

The following values are reloadable if the mod has Debug mode enabled: MaxAngularSpeed, TargetAngleSpeed, LimitsHighestAngle, and LimitsDisplay.

Spinning Module

Similarly to the Steering Module, the Spinning Module allows rotation of the block along one axis, controlled by the user. However the Spinning Module behaves like a wheel, rather than a steering hinge.

Example:

<Modules>
    <Spinning>
        <Forward key="forward" />
        <Backward key="backward" />

        <SpeedSlider key="speed" />
        <AccelerationSlider key="acceleration" />

        <AutomaticToggle key="automatic" />
        <ToggleModeToggle key="toggle-mode" />

        <Axis>Z</Axis>
        <MaxAngularSpeed>50</MaxAngularSpeed>
    </Spinning>
</Modules>

Forward, Backward: Keybindings to control the block. References to keys that must be defined in the ModuleMapperTypes element.
SpeedSlider: Defines the speed range possible. Reference to a slider that must be defined in the ModuleMapperTypes element.
AccelerationSlider: Defines the possible accelerations. Reference to a slider that must be defined in the ModuleMapperTypes element. Infinity results in almost instant acceleration and deceleration.
AutomaticToggle: Toggle mapper type for turning automatic mode on and off. Reference to a toggle that must be defined in the ModuleMapperTypes element.
ToggleModeToggle: Toggle mapper type for turning toggle mode on and off. Reference to a toggle that must be defined in the ModuleMapperTypes element.
Axis: The local axis that the block rotates around; X, Y, or Z.
MaxAngularSpeed: Limits how fast the block's Rigidbody can possibly rotate. See Rigidbody.maxAngularVelocity in the Unity documentation for more information. Optional, default is 50.

Axis and MaxAngularSpeed are reloadable. If the Axis is changed, any wheels currently in simulation will not be able to rotate anymore until the simulation is restarted.

Shooting Module

The shooting module can be used to add cannon- or crossbow-like behaviour to a block.

Example:

<Modules>
    <Shooting>
        <Projectile>
            <Mesh name="mesh" />
            <Texture name="texture" />

            <Colliders>
                <SphereCollider>
                    <Position x="0" y="0" z="0" />
                    <Radius>1</Radius>
                </SphereCollider>
            </Colliders>

            <Mass>0.1</Mass>
            <Drag>0.0</Drag>
            <AngularDrag>5.0</AngularDrag>
            <IgnoreGravity>False</IgnoreGravity>

            <EntityDamage>150</EntityDamage>
            <BlockDamage>1</BlockDamage>

            <Attaches>false</Attaches>

            <FireInteraction ... />
        </Projectile>

        <FireKey key="fire" />
        <PowerSlider key="power" />
        <RateOfFireSlider key="rate-of-fire" />
        <HoldToShootToggle key="hold-to-shoot" />

        <ProjectileStart>
            <Position x="0.0" y="0.0" z="1.0" />
            <Rotation x="0.0" y="0.0" z="0.0" />
        </ProjectileStart>

        <ShowPlaceholderProjectile>False</ShowPlaceholderProjectile>

        <DefaultAmmo>5</DefaultAmmo>
        <AmmoType>Arrow</AmmoType>

        <ProjectilesExplode>False</ProjectilesExplode>

        <SupportsExplosionGodTool>False</SupportsExplosionGodTool>
        <ProjectilesDespawnImmediately>False</ProjectilesDespawnImmediately>
        <TriggeredByFire>False</TriggeredByFire>

        <RecoilMultiplier>0.1</RecoilMultiplier>

        <PoolSize>10</PoolSize>

        <Sounds>
            <CrossbowSounds />
            <CannonSound />
            <AudioClip name="some-resource-name "/>
        </Sounds>
    </Shooting>
</Modules>

Projectile: Defines the projectile that is shot.
- Mesh: Mesh of the projectile. Resource defined in the manifest.
- Texture: Texture of the projectile. Resource defined in the manifest.
- Colliders: Colliders of the projectile. See Colliders.
- Mass: Mass of the projectile.
- Drag: Drag of the projectile. Optional, default: 0.
- AngularDrag: Angular drag of the projectile. Optional, default: 5.
- IgnoreGravity: Whether the projectile should ignore gravity.
- EntityDamage: How much damage an entity takes on colliding with the projectile. Optional, default: 100.
- BlockDamage: How much damage a block takes on colliding with the projectile. Optional, default: 1.
- Attaches: Whether the projectile attaches to objects it hits. For context, the crossbow arrow attaches but the cannonball doesn't.
- FireInteraction: Determines how the projectile is going to interact with fire. See FireInteraction for more information. Optional, default is no interaction with fire.
FireKey: Key used for shooting. Reference to a key that must be defined in the ModuleMapperTypes element.
PowerSlider: Slider to define the power with which the projectile is shot. Reference to a slider that must be defined in the ModuleMapperTypes element.
RateOfFireSlider: Slider to define the rate of fire with which the projectile is shot. Reference to a slider that must be defined in the ModuleMapperTypes element.
HoldToShootToggle: Toggle to choose between turning automatic firing on/off or having to hold/press the key to fire. Reference to a toggle that must be defined in the ModuleMapperTypes element.
ProjectileStart: Defines where projectiles are spawned and in what direction they are shot. This is visualized by a metal spike pointing in the direction of shooting, if Debug is turned on on the block.
ShowPlaceholderProjectile: Whether to show a copy of the projectile during building and during simulation, while not shooting. The projectile will be shown exactly where the projectile will be spawned. Hint: The ExtraIconObjects element of the Block element can be useful when this is used. Optional, default: False.
DefaultAmmo: How often the block can shoot without reloading.
AmmoType: What reload events the module should respond to. Module is always reloaded by the All type, this can be used to also respond to Arrow, Cannon, or Fire. Set this to All if the module should only respond to events with type All. Optional, default: All.
ProjectilesExplode: Whether projectiles explode on impact. Optional, default: False.
SupportsExplosionGodTool: Whether or not projectiles should explode on collision if the "Explosive Cannonballs" god tool is enabled. Optional, default: True.
ProjectilesDespawnImmediately: Whether projectiles immediately disappear after impacting. Optional, default: False.
TriggeredByFire: Whether the block should shoot automatically when it is on fire / being heated, the way that the cannon does. Optional, default: False.
RecoilMultiplier: The force applied to the projectile is multiplied by this factor before being applied as recoil to the block itself. That isn't entirely realistic (unless you set it to 1) but can be tweaked for better gameplay. Optional, default: 0.1.
PoolSize: Projectiles are pre-created and then the objects are reused. This defines how many projectile objects are available in singleplayer. In multiplayer, the size is fixed and the same for all projectile types. Optional, default: 10.
Sounds: Sounds to play when a projectile is fired. Optional, by default no sound is played. One of the sounds specified is chosen at random every time.

Possible elements: - CrossbowSounds, all the sounds that the crossbow uses. - CannonSound, the sound that is used by the cannon. - AudioClip, a reference to any AudioClip defined as a mod resource.

Everything except ShowPlaceholderProjectile, the mapper type references, the pool size and the sounds can be reloaded.

Spewing Module

The spewing module can be used to add particle systems to a block.

Each spewing module has a number of settings applying to all its particle systems, as well as one or more particle system, with associated settings each.

Global Settings

<Modules>
    <Spewing>
        <TriggerKey key="trigger" />
        <RangeSlider key="range" />
        <HoldToFireToggle key="hold-to-fire" />
        <ToggleTimeLimit>10</ToggleTimeLimit>
        <BaseAmmo>10</BaseAmmo>
        <AcceptFireAmmo>False</AcceptFireAmmo>
    </Spewing>
</Modules>

TriggerKey: Key to trigger the particle systems. Reference to a key that must be defined in the ModuleMapperTypes element.
RangeSlider: A slider definition for the range slider. Reference to a slider that must be defined in the ModuleMapperTypes element.
HoldToFireToggle: A toggle definition for the Hold To Fire toggle. Reference to a toggle that must be defined in the ModuleMapperTypes element.
ToggleTimeLimit: Optional, if specified and the module is not in hold to fire mode, the particle systems will automatically be turned off after the specified amount of time after toggling it on.
BaseAmmo: How long the particles can be fired without reloading, in seconds.
AcceptFireAmmo: If true, will reload using "Fire" and "All" ammunition. If false, will only reload using "All" ammunition. Default is false.

Defining Particle Systems

The definitions for the particle system are placed in the ParticleSystems element. There are three types of particles available: Water, Fire, Steam, and Custom.

This type just controls the visuals of the particles, not any actual behaviour with regards to fire, that can be configured separately as described below.

If the block has Debug mode enabled, the whole ParticleSystems element can be reloaded.

All particle types have some required options:

StartPosition: Where, relative to the block, the particles are emitted.
Direction: in which direction the particles are emitted.
StartSpeed: Base speed of the particles when being emitted. The actual startSpeed property is computed as StartSpeed * Range Slider Value + 0.5.

For a Custom particle system, one more element is needed to specify the texture that should be used: <Texture name="some-texture-resource-name" />.

In addition, it is possible to optionally specify these parameters:

LifetimeMultiplier: Scales the lifetime of the particles. The default depends on the type of particle. This value acts as a multiplier on the respective default. The default of this is 1 accordingly.
DousesFire: If included, a fire that collides with any particles will be extinguished. This requires the particle system to have the Collisions module enabled.
AddForce: Adds extra force to particle collisions. This requires the particle system to have the Collisions module enabled.
Collisions: By default, particle collisions are disabled. This can be used to turn them on and configure them.

Its parameters, as shown below, directly set the corresponding property in Unity.

The values shown below are the default values, and the same that the water particles of the normal water cannon use.

There are two ways of making a particle system ignite new fire:

FireTrigger: A BoxCollider element, every burnable object entering the collider while the particles are on will be set on fire.
StartsFire: An empty element, similar to DousesFire. Uses particle collisions to start fire, and requires the Collisions module to be enabled.

Which one to use depends on how the particle system should behave. The normal flamethrower uses the fire trigger method for example, because its fire does not have any collisions and passes through objects.

If you had something that bounces off of other objects, you should probably use the StartsFire method, otherwise objects that are not ever hit by the particles will get ignited.

Example for two particle systems, one using fire particles and one using water particles. For demonstration, the fire particles actually douse fire and the water particles ignite burnable blocks:

<Spewing>
    <ParticleSystems>
        <Fire>
            <StartPosition x="0" y="0" z="-0.5" />
            <Direction x="0" y="0" z="1" />
            <StartSpeed>2.0</StartSpeed>

            <RangeMultiplier>1</RangeMultiplier>
            <LifetimeMultiplier>2.0</LifetimeMultiplier>

            <AddForce>1.5</AddForce>
            <DousesFire />

            <Collisions>
                <Dampen>0.25</Dampen>
                <Bounce>0.6</Bounce>
                <LifetimeLoss>0.01</LifetimeLoss>
                <MinKillSpeed>0.01</MinKillSpeed>
                <MaxKillSpeed>10000</MaxKillSpeed>
                <RadiusScale>0.01</RadiusScale>
            </Collisions>
        </Fire>

        <Water>
            <StartPosition x="0.5" y="0" z="0" />
            <Direction x="1" y="0" z="0" />

            <RangeMultiplier>1</RangeMultiplier>

            <FireTrigger>
                <Position x="5" y="0" z="0" />
                <Rotation x="0" y="0" z="0" />
                <Scale x="9" y="1.5" z="1.5" />
            </FireTrigger>
        </Water>
    </ParticleSystems>
</Spewing>