Modding:Turns, Segments, and Actions

This page is about modding. See the modding overview for an abstract on modding.
For best results, it's recommended to have read the following topics before this one:

The passage of time and the queue of player/creature actions in the game is controlled by XRL.Core.ActionManager, particularly in the RunSegment method, which controls the "action queue". The action queue relates closely to the concept of action cost. The main time-keeping concepts include:

Segment Marks the passage of 100 action points on the action queue, or one-tenth of a standard "turn". Activating or deactivating items with a power switch takes this amount of time. The passage of segments is not tied to the player's speed or actions.
Turn Marks the passage of 1000 action points on the action queue. This is one "standard turn" - it is the standard time it takes the player to take most actions if the player has 100 Quickness. The passage of turns is not tied to the player's speed or actions (for example, the player can act multiple times per turn if they have high quickness)
Action Marks the passage of one action, such as a player action (moving one tile, firing a missile weapon, etcetera). This is a dynamic concept that can change duration depending on the player's Quickness and other factors. This is directly tied to the player's actions.

There are events associated with all of these concepts which you can use while coding a mod. Here is a sample part that receives events corresponding to each concept. You can attach this to an object to observe each of these events in the in-game message log.

using System;

namespace XRL.World.Parts
{
    [Serializable]
    public class TimePassageTest : IPart
    {
		public override bool WantEvent(int ID, int cascade)
		{
			return base.WantEvent(ID, cascade)
                || ID == EndTurnEvent.ID
                || ID == EndActionEvent.ID
                || ID == EndSegmentEvent.ID;
        }

        public override bool HandleEvent(EndTurnEvent E)
        {
            // This event occurs after the passage of each "standard turn". If the player's quickness is 100, this
            // event will fire once each time the player takes an action. However, if the player has higher
            // quickness, such as 200, this event will only fire once every time the player takes two actions.
            IComponent<GameObject>.AddPlayerMessage("EndTurn event on TimePassageTest part");
            return base.HandleEvent(E);
        }

        public override bool HandleEvent(EndActionEvent E)
        {
            // This event fires every time the player takes an action, regardless of how long that action takes
            // or how quick the player is.
            IComponent<GameObject>.AddPlayerMessage("EndAction event on TimePassageTest part");
            return base.HandleEvent(E);
        }

        public override bool HandleEvent(EndSegmentEvent E)
        {
            // This event fires 10 times for each "standard turn" - in other words, it fires each time that 100
            // action points are processed through the action queue. If the player has quickness of 100, this
            // will fire 10 times each time the player takes a typical action.
            IComponent<GameObject>.AddPlayerMessage("EndSegment event on TimePassageTest part");
            return base.HandleEvent(E);
        }
    }
}