Resources (creatures and items)

1. Resource file (resource.xml)

resource.xml files define the properties of resources: creatures and items. Below is a sample resource.xml file, with links to documentation for every attribute.

• (Almost) every attribute is optional, so in practice there's no need to specify them all in your resource.xml files.
• Note that sample below shows properties for resource of type WalkAttack (indicating TWalkAttackCreatureResource class), there are other resource types (for creatures and items) with a little different properties.
• See manual about resources for information how to initialize resources (creatures and items) from such files.

<?xml version="1.0"?>

<resource
  name="RequiredCreatureName"
  type="WalkAttack"
  orientation="default"
  knockback_speed="1.0"
  collides_when_dead="False"
  knockback_distance="4.0"
  flying="False"
  sound_die_tied_to_creature="True"
  default_max_life="100.0"
  radius="0.0"
  middle_height="0.5"
  sound_sudden_pain=""
  sound_die=""
  scale_min=""
  scale_max=""
  move_speed="1.0"
  min_life_loss_to_hurt="0.0"
  chance_to_hurt="1.0"
  max_height_acceptable_to_fall="1.5"
  random_walk_distance="10.0"
  remove_dead="False"
  preferred_distance="2.0"
  smell_distance="0.0"
  always_prepared="False"
  fall_speed="10.0"
  grow_speed="5.0"
  receive_shadow_volumes="True"
  cast_shadow_volumes="True"
  >

  <!-- See lower on this page for explanation how to set animations. -->
  <model url="my-creature.gltf"
    pool="auto"
    default_animation_transition="0.0"
  >
    <idle         animation_name="Idle" />
    <idle_to_walk animation_name="IdleToWalk" />
    <walk         animation_name="Walk" />
    <fire_missile animation_name="FireMissile" />
    <attack       animation_name="Attack" />
    <die          animation_name="Die" />
    <die_back     animation_name="DieBack" />
    <hurt         animation_name="Hurt" />
  </model>

  <attack
    knockback_distance="0.0"
    time="0.0"
    max_distance="2.0"
    max_angle="0.523598776"
    min_delay="2.0"
    sound_hit=""
    sound_start="" >
    <damage
      const="0.0"
      random="0.0" />
  </attack>

  <fire_missile
    time="0.0"
    max_distance="30.0"
    max_angle="0.523598776"
    min_delay="2.0"
    sound=""
    name=""
    height="0.5" />

  <fall>
    <sound
      min_height="1.0"
      name="creature_fall" />
    <damage
      min_height="5.0"
      scale_min="0.8"
      scale_max="1.2" />
  </fall>

  <run_away
    life="0.3"
    distance="10.0" />

  <visibility
    angle="2.094395102" />
</resource>

2. Resource type

The type attribute determines the exact class (ObjectPascal implementation) used to instantiate this resource. You can use the same type many types of course, for example you can define many creatures of type WalkAttack or Missile and many items of type Item.

This type determines the behavior that is coded in ObjectPascal — like creature artificial intelligence, whether item can be equipped, what happens when item is used and so on.

The type also determines available attributes and animations of this resource. For example, only creature type WalkAttack (or it's descendants) have the <attack> animation. See the properties of resource classes to know what is available:

• T3DResource
  • TCreatureResource
    • TWalkAttackCreatureResource
    • TMissileCreatureResource
    • TStillCreatureResource
  • TItemResource
    • TItemWeaponResource

3. Place resource model above the ground

Resources models (creatures, items and such) should be modeled around 0,0,0 point. In case of resources using gravity (items and non-flying creatures), they will be placed on the ground relative to the 0 level of their model. In other words, if you want your model to float slightly above the ground, you can just move it higher above the 0 level. If the model is slightly below 0 level, it will sink into the ground. This is usually the most comfortable approach.

For flying resources (not using gravity), this doesn't matter, basically you can place 0,0,0 wherever you like. See TCastleTransform.MiddleHeight for precise details.

4. Animations of resources

Resources, like creatures and items, display an animation appropriate to their current state. For example, a creature state may be "idle" or "attacking" or "dying", and it will cause appropriate animation. A developer can also add additional animation types to the creature or item (by creating a T3DResourceAnimation instance and adding it to a T3DResource descendant).

Inside the <model> element of the creature/item resource.xml file you specify from where to load particular animations. You should use one file for all the animations, like glTF file exported from Blender with Blender actions for each required animation. See the example inside the resource_animations engine example. The data/ subdirectory of it shows examples of how you can define <model>, discussed below. It is also a great program to test your own creatures/items animations (before using in the actual game), you can load their resource.xml using the "Add resource..." button and directly play loaded animations.

You declare it in resource.xml file like this:

<model url="model.x3d" pool="10">
  <stand animation_name="TimeSensorStand"/>
  <walk  animation_name="TimeSensorWalk"/>
</model>

The "animation_name" recognizes animations defined in various formats (and expressed in X3D using TimeSensor), just like the engine TCastleSceneCore.PlayAnimation method. You can see these animations in the Castle Model Viewer by turning on Animations panel.

The looping is done automatically for animations that require it (like walk). The value of loop attribute in castle-anim-frames file, or TimeSensor.loop field in X3D, is ignored.

4.1. Deprecated: Separate animations in separate files

The deprecated way (do not use in new games!) to define animations is to use a separate model for each animation state, like this:

<model>
  <stand url="stand.x3d" animation_name="MainTimeSensor"/>
  <walk  url="walk.x3d"  animation_name="MainTimeSensor"/>
</model>

You can omit the animation_name, it is then assumed to be just 'animation', which is the default animation name we read from castle-anim-frames and MD3 (Quake 3 engine format) files. If you use X3D files, the animation name should just match the TimeSensor node name (given like <TimeSensor DEF="MyAnimation"> in X3D XML files).

Example:

<model>
  <stand url="stand.castle-anim-frames"/>
  <walk  url="walk.castle-anim-frames"/>
</model>