Runtime error messages

Describes error messages that you are likely to get while developing agents, and gives suggestions on how to solve common problems.

---

The Creatures 3 engine provides very useful feedback whenever an error is detected, and as well as showing you which section of the code went wrong and for what reason it also gives you some options to deal with it. If an agent script goes wrong then you will be presented with some of the following options:

Brutal Ignore -
The virtual machine for the agent will carry on as if nothing went wrong in the first place, this can be Very Bad (TM). Despite the option being there you'd be best off not using it. For most agents and most commands this is not a sensible option, try one of the others below.

Freeze Agent -
This will pause the agent (exactly the same as if you'd used the PAUS command on it). This means the agent will not respond to any events and will have its timer frozen. One strange side effect of this is that if you freeze an agent, and then pause the game, that agent will become un-paused while everything else freezes.

Kill Agent -
The offending agent will be removed from the game (exactly the same as if you'd performed a KILL TARG on the agent). This is by far the safest option, but if you have made a complicated series of agents that all have pointers to each other then removing one of them may well throw up new errors as the others try to TARG to it and can no longer find it. This can be avoided though by making sure every time you change TARG you make it bullet proof by verifying it really exists first.

Stop Script -
This will stop the current script. If the agent is on a timer though be aware that next time the agent ticks it will run a script again.

So now you now what to do when you see the dialogue ... but how can you fix it?

The error message will list the classifier of the agent that has broken (and a name if you have included Agent Help for the agent), the script it was running when things went pear-shaped and its unique ID. Some of the error messages also provide more details on the exact nature of the problem, for example, stating the XY position it tried to move to when an invalid map position error was generated.

Hopefully the error message alone will help you get to the bottom of what is wrong, but just in case here's a small breakdown of some of the more common errors that occurred during development and some ways to deal with them.

Error message	Analysis	Common causes	Solutions
Invalid targ	The agents script has attempted to change targ to another agent ... but that agent no longer exists.	-The agent you were trying to target has died, or been removed by the game	-Always verify that when you change targ the targ actually exists. You can do this with a simple 'doif targ ne null' as soon as you have changed targ. REMEMBER: that if you do this you will need to change targ back to the ownr, and then carry on with something else. -Whenever you perform an ENUM, ESEE or ETCH make sure the enumerate-next loop is contained within an INST (and add SLOW after the NEXT if you want to return to normal speed execution).
Invalid map position	Your agent has attempted to do something that has placed it out of the map system. This error is only relevant to agents with ATTR set such that they take notice of room boundaries.	- Tried to create an agent where there is not the physical room for it (narrow confined spaces) -Tried to create an agent completely outside of the room system. - The animation of the agent changed the size of the agents bounding box which made some of it move out of the room system.	- If you have an agent that creates other agents, always use the TMVT command to make sure the position you are trying to move to is valid. If the position is valid then you can carry on with the MVTO, otherwise you should do something else. - Make sure your agent has one size bounding box for all of its frames. If this is not the case then you are likely to get this error.
Pose change failed	The agent attempted to change to a pose that doesn't exist for it.	- The POSE command is using a value that doesn't exist - The BASE command was used at some point, and so all animation commands are in relation to that base. - When the object was created you didn't specify the correct number of poses and/or the correct base index in the sprite file.	- Check your values (the dialogue will show the value it was trying to use). - If you use BASE anywhere in your code it is good practice to use it in front of every animation and pose command. - Check your NEW: command and make sure you included all the images you wanted.
Failed to get room ID	The agent was attempting to read from the environment but was unable to do this.	- The agent may have been picked up and at that time was being held so that it was outside of the room system.	- Whenever you want to read something from the world, always make sure that the agent is still in the world. You can do this with a simple 'doif room targ <> -1' check around the reading operation.
Failed to get room property	see above	see above	see above
Incompatible type agent/decimal/string expected	The agent script has attempted to perform an operation on a variable which is of the wrong type.	- Trying to perform arithmetic operations on a variable that is not a decimal - Attempting to TARG using a variable that is not an agent pointer - Attempting to perform string operations using a variable that is not a string	- Double check all the variables you are using. If you are assuming a variable is a decimal with default value 0 then try explicitly declaring it as a 0 decimal value (setv 0) - Double check all the variables you are using. By default variables are set to 0, not null, so if you want to perform an agent check on a variable (doif eq null), you have to specifically set it to null at some point to initialise it as an agent variable. - Double check all the variables you are using.
ATTR/PERM change caused invalid map position	The attributes of the agent, or its permeability, have changed and this has highlighted the fact it is out of the room system. Whenever ATTR or PERM changes the engine will check the agents position for validity.	- The agent script changes ATTR from 'doesn't suffer collisions' to 'suffers collisions' - but the agent had moved out of the room system. - The agent script changes PERM from a less restrictive state to a more restrictive state. While this was happening though the agent was crossing a boundary which it would not be able to after the change.	- ATTR changes should only be done when the agent is definitely in the room system. Try using TMVT to test whether the position is valid. - Try to change the PERM only when the agent is at rest.

---

Topic Keywords: agent caos creatures3 dockingstation