ItemActionComponent - acrimi/Raven GitHub Wiki

Extends StatefulComponent

ItemActionComponent is an extension of StatefulComponent that represents the active state of a usable item. It also defines what entities should be spawned when any given item becomes active.

Each key in the component's configuration corresponds to an item name, and defines what entities should be spawned for that item. Any item that does not have a configuration specified will, by default, spawn a single entity with a type equal to the item name itself.

The component doesn't support custom enter/exit states or a non-default initial state. Instead, the component always has a single exit state named "cooldown" with a variable duration that is defined for each item. It also doesn't support a custom duration for the "active" state, which will always be set to infinite. Instead, the component will be automatically deactivated based on the entities that have been spawned for the currently active item. This deactivation will happen after two conditions are met:

  • All non-child entities have been spawned
  • All child entities have been spawned and subsequently destroyed

Configuration

When used inside the components block, the initial state of the component can be configured with the following parameters:

Key Type Description
[itemName] object|object[]|string The configuration that will be used to spawn entities for the item named by this key. If the value of spawn is an object, it can be passed directly, including the cooldown parameter, as a shorthand.
      cooldown float A delay, in seconds, that will be added between when all entities have been spawned/destroyed and when the component will deactivate. Defaults to 0
      spawn (string|object)[]|string|object An array of configurations defining what entities will be spawned for this item. Simple entities that require no configuration can be specified as a simple string representing their type. If only one entity should be spawned, the array structure can be omitted as a shorthand.
            type string The type of entity to spawn. If omitted, the type will default to the item name.
            child boolean Whether the spawned entity should be attached as a child of the spawning entity's TransformComponent or as a standalone entity. Defaults to true.
            delay float A delay, in seconds, to wait before spawning this entity after this item becomes active
            velocity float|object A velocity that will be applied to the spawned entity relative to the spawning entity's orientation. A simple forward velocity can be supplied as a direct velocity, or a 2-dimensional relative velocity can be supplied as an object.
                  lateral float The lateral velocity of the spawned entity relative to the spawning entity's orientation. Positive values move to the spawning entity's right, negative values to the left.
                  forward float The forward velocity of the spawned entity relative to the spawning entity's orientation. Positive values move towards the front of the spawning entity, negative values towards the back.
            alignment string The case-insensitive name of the alignment that should be used to position the spawned entity relative to the parent entity. See EntityAlignment for all values. Defaults to "center".
            offset object An object containing the offset that should be applied to the spawned entity relative to its initial alignment. Individual offsets can be configured for each entity orientation.
                  x float The default x offset that will be used for any orientation that doesn't have a custom offset specified
                  y float The default y offset that will be used for any orientation that doesn't have a custom offset specified
                  lateral float The lateral offset of the spawned entity relative to the spawning entity's orientation. Positive values move to the spawning entity's right, negative values to the left. Ignored if either x or y are defined.
                  forward float The forward offset of the spawned entity relative to the spawning entity's orientation. Positive values move towards the front of the spawning entity, negative values towards the back. Ignored if either x or y are defined.
                  mirrored boolean Whether or not the left/right offsets should be mirrored around the entity's horizontal axis when the opposite direction is missing. This can help avoid creating redundant configurations for each direction. Defaults to true.
                  [orientation] object An object containing the offsets that should be applied to the spawned entity for the orientation named by this key. The key should correspond to the lowercased name of an EntityOrientation (eg "right", "up", etc).
                        x float The x offset that will be applied for this orientation
                        y float The y offset that will be applied for this orientation
            initializationData object An optional configuration object that will be applied to the spawned entity. Supports all properties allowed in entity templates. Will be merged with any existing templates configured for the entity's type.

Examples:

"ItemActionComponent": {
  "bomb": "explosive",
  "spear": {
    "type": "basicSpear",
    "delay": 0.2,
    "child": true
  }
}
"ItemActionComponent": {
  "dagger": {
    "type": "knife",
    "child": false,
    "delay": 0.2,
    "velocity": 400,
    "offset": {
      "x": -1,
      "y": -2,
      "mirrored": true,
      "up": {
        "x": -1,
        "y": 2
      },
      "right": {
        "x": 2,
        "y": -1
      }
    },
    "initializationData": {
      "components": {
        "HitBoxComponent": {
          "attached": "true"
        }
      },
      "events": {
        "destroyed": {
          "action": "EventAction",
          "eventName": "daggerThrown"
        }
      }
    }
  }
}
"ItemActionComponent": {
  "knife": {
    "child": false,
    "cooldown": 0.1,
    "delay": 0.2,
    "velocity": 400,
    "alignment": "origin",
    "offset": {
      "lateral": 2,
      "forward": 1
    }
  }
}
"ItemActionComponent": {
  "spell": [
    "smoke",
    {
      "type": "magicBullet",
      "child": false,
      "delay": 0.2,
      "velocity": {
        "forward": 400,
        "lateral": 50
      }
    },
    {
      "type": "magicBullet",
      "child": false,
      "delay": 0.2,
      "velocity": {
        "forward": 400,
        "lateral": -50
      }
    }
  ]
}
"ItemActionComponent": {
  "bigSpell": {
    "cooldown": 1.1,
    "spawn": [
      "smoke",
      {
        "type": "barrier",
        "child": true,
        "delay": 0.1
      },
      {
        "type": "magicBullet",
        "child": false,
        "delay": 0.2,
        "velocity": {
          "forward": 400,
          "lateral": 50
        }
      },
      {
        "type": "magicBullet",
        "child": false,
        "delay": 0.2,
        "velocity": {
          "forward": 400,
          "lateral": -50
        }
      }
    ]
  }
}

Properties

The following properties are readable by property accessors (eg render state and persistence definitions):

Key Type Description
itemName string The name of the currently active item
isActive* boolean Whether or not the current state is "active"
isInactive* boolean Whether or not the current state is "inactive"
state* string The name of the current state
progress* float The percentage, from 0 to 1, of how much time has elapsed for the current state relative to its duration (elapsedTime / duration). If the current state has an infinite duration, this value is always 0.

* from StatefulComponent

⚠️ **GitHub.com Fallback** ⚠️