RenderComponent - acrimi/Raven GitHub Wiki

RenderComponent is what controls an entity's ability to be rendered on screen. For simple entities, it can function as a simple marker component, but it can also be configured with a RenderStateResolver, which will be used to dynamically determine which sprite/animation should be rendered based on the entity's state. An array of RenderBehavior names can also be supplied to specify advanced rendering logic.

Configuration

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

Key	Type	Description
zIndex	int	Determines the rendering order of entities within a single layer. Higher values will render on top of lower values. Takes priority over y position sorting, if used. Defaults to 0.
behaviors	string[]	One or more names of RenderBehaviors that should be applied to this entity. The pre-processing logic of these behaviors will be applied before global RenderBehaviors, and the post-processing logic will be applied after global RenderBehaviors.
states	object[]	An array of state configurations that will be used to determine how the entity is rendered. If none of the states are satisfied, the entity will be rendered using its default render state, if defined.
name	string	The name of the render state to display if the conditional in when is met
priority	float	Value to override the default priority of this state. If multiple states can be satisfied at once, by default they are prioritized by the order in which they are defined. Giving a positive or negative number for priority can override that ordering. Defaults to 0.
timeSource	string	An optional name of a TimedComponent that will be used to determine the current elapsed time of this state. By default the state will track its own elapsed time once it becomes active.
when	object|object[]	A configuration representing the conditional logic that must be satisfied for this state to become active. Conditionals can be nested many layers deep using the all and any keys. If an array as passed, it will be treated as an all (conjunctive) conditional.
all	object[]	An array of nested conditionals that will be evaluated conjunctively to determine the result of this conditional. If defined, all parameters below are ignored.
any	object[]	An array of nested conditionals that will be evaluated disjunctively to determine the result of this conditional. If defined, all parameters below are ignored.
id	object|int	A metadata filter that will be evaluated against the entity's id property. For the "is" case, the id value can be supplied directly as a shorthand. If defined, all parameters below, other than type and tag, are ingored.
is	int	An id value to compare against the entity's id. If the values are the same, this condition will resolve to true.
not	int	An id value to compare against the entity's id. If the values are not the same, this condition will resolve to true. Ignored if is is also defined.
type	object|string	A metadata filter that will be evaluated against the entity's type property. For the "is" case, the type value can be supplied directly as a shorthand. If defined, all parameters below, other than tag, are ingored.
is	string	A type value to compare against the entity's type. If the values are the same, this condition will resolve to true.
not	string	A type value to compare against the entity's type. If the values are not the same, this condition will resolve to true. Ignored if is is also defined.
tag	object|string	A metadata filter that will be evaluated against the entity's tag property. For the "is" case, the tag value can be supplied directly as a shorthand. If defined, all other parameters below are ingored.
is	string	A tag value to compare against the entity's tag. If the values are the same, this condition will resolve to true.
not	string	A tag value to compare against the entity's tag. If the values are not the same, this condition will resolve to true. Ignored if is is also defined.
child	object|string	A filter that will be evaluated against the entity's child entities to determine the result of this conditional. If any children match this configuration, this conditional is satisfied. The special value "any" can be specified to match any child. If defined, all parameters below, other than linkedBy, are ignored.
linkedBy	string	The name of a ChildLinkedComponent to query when testing the child filter. If specified, only the child linked by that component will be evaluated. If the component does not exist, or is not a ChildLinkedComponent, the result of this conditional will be false.
[componentName]	string	A property name exposed by the component that is named by this key. The value of this property will be looked up and compared against the specified operator (all parameters below) to determine the result of this conditional. Only one component-property pair and one operator can be defined per conditional. All components support the "isAttached" property, which returns true if the component is currently attached to the entity. Refer to the "Properties" section of each component's reference page for all other supported values.
is	string|number|boolean	Resolves this conditional to true if the component property value is equal to this value. For boolean properties, "is": true can be omitted as it is the default operation.
isNot	string|number|boolean	Resolves this conditional to true if the component property value is not equal to this value
lessThan	number	Resolves this conditional to true if the component property value is a number and is less than this value
greaterThan	number	Resolves this conditional to true if the component property value is a number and is greater than this value
notLessThan	number	Resolves this conditional to true if the component property value is a number and is greater than or equal to this value
notGreaterThan	number	Resolves this conditional to true if the component property value is a number and is less than or equal to this value
includes	string|number|boolean	Resolves this conditional to true if the component property value is a collection and includes this value as a member
excludes	string|number|boolean	Resolves this conditional to true if the component property value is a collection and does not include this value as a member

Examples:

"RenderComponent": {
  "zIndex": 1
}

"RenderComponent": {
  "behaviors": [
    "ShadowBehavior",
    "OutlineBehavior"
  ]
}

"RenderComponent": {
  "zIndex": -1,
  "behaviors": [
    "ShadowBehavior"
  ],
  "states": [
    {
      "name": "dying",
      "priority": -1,
      "timeSource": "DeathComponent",
      "when": {
        "DeathComponent": "isActive"
      }
    },
    {
      "name": "run",
      "when": [
        {
          "MovementComponent": "isMoving"
        },
        {
          "PhysicsComponent": "speed",
          "greaterThan": 50
        }
      ]
    },
    {
      "name": "customIdle",
      "when": {
        "type": {
          "not": "subType"
        },
        "tag": {
          "is": "specialCharacter"
        }
      }
    }
  ]
}

"RenderComponent": {
  "states": [
    {
      "name": "run",
      "when": {
        "all": [
          {
            "MovementComponent": "isMoving"
          },
          {
            "PhysicsComponent": "speed",
            "notLessThan": 50
          }
        ]
      }
    },
    {
      "name": "sweat",
      "when": {
        "any": [
          {
            "PushComponent": "isActive",
            "is": true
          },
          {
            "PullComponent": "isInactive",
            "isNot": true
          },
          {
            "tag": "sweatyCharacter"
          }
        ]
      }
    }
  ]
}

"RenderComponent": {
  "states": [
    {
      "name": "carry",
      "when": {
        "child": "any",
        "linkedBy": "CarryComponent"
      }
    },
    {
      "name": "full",
      "when": {
        "child": {
          "type": "gold",
          "tag": "bigTreasure"
        },
        "linkedBy": "ContainerComponent"
      }
    }
  ]
}

"RenderComponent": {
  "states": [
    {
      "name": "easterEgg",
      "when": {
        "all": [
          {
            "TerrainAwareComponent": "terrainNames",
            "includes": "grass"
          },
          {
            "TerrainAwareComponent": "terrainNames",
            "excludes": "snow"
          },
          {
            "any": [
              {
                "PushComponent": "isActive",
                "is": true
              },
              {
                "PullComponent": "isInactive",
                "isNot": true
              }
            ]
          },
          {
            "child": {
              "type": "lava"
            },
            "linkedBy": "ContainerComponent"
          }
        ]
      }
    }
  ]
}

Properties

This component has no exposed properties