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"
  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 export animations
       and define <model> element. Below we only show all possible attributes,
       in practice you will not want to set them all. -->
  <model url="main.castle-anim-frames">
    <idle         url="idle.castle-anim-frames"         animation_name="Idle" />
    <idle_to_walk url="idle_to_walk.castle-anim-frames" animation_name="IdleToWalk" />
    <walk         url="walk.castle-anim-frames"         animation_name="Walk" />
    <fire_missile url="fire_missile.castle-anim-frames" animation_name="FireMissile" />
    <attack       url="attack.castle-anim-frames"       animation_name="Attack" />
    <die          url="die.castle-anim-frames"          animation_name="Die" />
    <die_back     url="die_back.castle-anim-frames"     animation_name="DieBack" />
    <hurt         url="hurt.castle-anim-frames"         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. Orientation of resource 3D 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, always display an animation appropriate to their current state. For example, a creature state may be "standing" 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 can use separate 3D files for each animation, or a single 3D file for all of the animations, or any combination of the above.

You can see the example of all the approaches inside the examples/resource_animations demo. 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.

There are two approaches to indicate animations in <model> element in resource.xml file. Which one to choose depends on what 3D modeler / exporter you use to design your models:

1. The best way (low memory usage and short loading time) is to use a single model with many animations inside. All the important 3D model formats support it: X3D, castle-anim-frames, Spine JSON, etc.).

   You declare it in resource.xml file like this:

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

   What exactly is an "animation" depends on the initial format, but internally an animation is always a single named X3D TimeSensor node. Our method PlayAnimation recognizes the same animations. And you can see these animations in the view3dscene menu Animation -> Named Animations.

2. You can also 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 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>

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.