Terrarium: Processing events, controlling your creature, and common pitfalls.
Figuring out which events you are going to need for your creature to process can be very difficult within the Terrarium, especially for new users overwhelmed by the idea of having to optionally handle up to 10 events. Some creature authors don't even hook an event and wonder why their creature is never called. Here are the events, in order that they are called, along with their purpose and how often they are called.
| Event |
Times Called |
Order |
Description |
| Load |
1 |
1 |
This event is called at the beginning of your turn. It is always called unless you have been skipped, in which case none of your events are called. This event is best used to set up your processing state in order to prepare for the remainder of the events. Many people erroneously use this event in order to do other processing that later gets overwritten by processing inside of the remaining events. |
| MoveCompleted |
0-1 |
2 |
If your move completed because you reached your destination, or you were blocked, then this event is fired. This event is best processed by storing the event args locally on your creature and processing movement in the Idle event along with the rest of the events. I highly recommend aggregating all data from events 2 through 9 so they can be processed by event 10 in one fell swoop. Note this event may or may not fire immediately following a movement action in your previous tick. This is a multi-round action and so the event can take multiple rounes before it fires. |
| AttackCompleted |
0-1 |
3 |
Your previous attack action has completed. This will happen if you previously attacked. Attacking is a one round event, and so this event will fire on the tick immediately following an attack. You can check how much damage you were able to do, and if the target was killed, or was able to escape without any damage being done. |
| EatCompleted |
0-1 |
4 |
Your previous eat action has completed. This will tell you if your eat action was successful. This is a one round even and will fire immediately following an eat action in your previous tick. |
| Teleported |
0-1 |
5 |
If you get teleported, either locally or remotely, this will notify you of that event immediately following your insertion back into the processing queue. Note the only evidence of your teleport is that you were sent back to the local terrarium, or your were teleported remotely. This event may be fired after your creature was taken out of the queue for multiple rounds. The results of the LocalTeleport property will greatly change how you process this event. |
| ReproduceCompleted |
0-1 |
6 |
This event tells you that your baby has been born. It gives you no information. However, this event, under normal circumstances, should fire IncubationTicks after you start your reproduction. This is normally 10 ticks, but under various circumstances can take much longer. |
| Born |
0-1 |
7 |
This is a brand new creature, and you were just born. The sole purpose of this event is to pass you a byte[] representing your Dna from the parent creature. This event should probably be processed in-line inside of the event, since it is only called once and it is used to set up your initial state information for your creature. |
| DefendCompleted |
0-1 |
8 |
If you tried to defend in the previous round then this event will fire. There is no notification of a success or failure on this action. Damage is computed within a random range based on your attributes, and so depending on the layout of the random numbers, you'll either take more or less damage. |
| Attacked |
0+ |
9 |
This event will fire once for every creature that attacks you in the previous round. You can use this event to get the Attacker, so that you can defend against them in the future. This is important, since if you don't get the attacker here, you might not see the attacker later in a Scan due to camouflage. On the following round, you will only be able to defend against a single creature, so choose carefully. |
| Idle |
1 |
10 |
This is the final event called in the sequence. Like Load it is guaranteed to be called, so long as you aren't being skipped. I highly recommend that the results of all previous actions be stored and saved to be processed in this event. Users always run into concurrency problems when logic from various events overwrites the logical decisions of other events, and it is so much easier to process your creature in a linear and deterministic manner. I almost think that a special inherited Animal class could be developed that allowed for just this model. |
I make some assertions in the descriptions of events that people might not like, but I will stick by them. I think that the conditional events 2-9 should always be used (with the exception of Born), to set state locally on the creature. Once the state is set, it should later be processed in Idle. A large number of creatures developed do the exact opposite of this. They instead put all of their logic in the Load event, and then later process all of the optional events. This leads me to a list of common pit-falls to watch out for.
- Make sure to hook at least one event. Some creatures forget to hook them (first time authors mainly), and then wonder whey they aren't getting called for processing.
- Make sure to process the TurnsSkipped property. Your creature may be going over the time limit and you may never know. Process the TurnsSkipped property so you can realize this. Once your creature is tuned, you should process this anyway to make sure you aren't waiting on events that will NEVER fire. Some creatures issue a move command and then wait for the MoveCompleted event. This even can be skipped over during a skipping turn and your creature would never get notified.
- Don't do extraneous processing in optional events, that you are later going to overwrite in the Idle event. Lots of authors wonder why the actions being set in their MoveCompleted event or Attacked event later get overwritten. It is because they aren't taking into account the code running in their Idle event. This is also a huge perf sink, since often creatures will run the same logic twice, from two locations in your code.
- Don't use the Load event for your main processing code. If you do, you are going to lose all of the extra information from the optional events that could help you short-circuit code or better process your turn. Also setting actions in the Load event can cause them to later be overwritten by code in your optional handlers.
- You have to hook the Teleported event. Most authors don't bother because they don't think it is important. Instead they rebuild their world state every single tick doing the same scans over and over again, not reusing information. The extra processing time used scanning could be going into more complex processing algorithms.
That is all for now. Enjoy!