UnrealScript Entry Points

This section contains links to per-class pages that define events. Although the code that handles an event can be overridden by any subclass, they are documented here at the level where they are defined (the least-derived class for which they are valid).

Please note that this section of the Wiki tree is intended for events only, not all method definitions. The goal is to separate out a documentation path that allows people to read through (and quickly reference) methods that are asynchronously called by the engine.

     +-/Object Events
       +-/Actor Events
         +-/Controller Events
           +-/PlayerController Events

Notes

• This is just a first pass by going through the UScript class sources. Please add any information you might have regarding how they actually work, caveats, etc.
• Descriptions with UScript comment prefix (//) are taken from UScript source comments when available. Need better descriptions perhaps. Feel free to remove them if you have a better description.
• I decided to strip out the argument prototype part to try to keep the pages a little more change-insensitive. It's arbitrary, but I think it's a good idea. (Eventually, it would be nice to cross-link everything here to a better description under the class documentation?)
• Eventually, I'd like to reorder events within the classes categorically (Karma, Collision, etc.)
• It's clear that there's going to be an overlap between the event listing here, and the class documentation elsewhere (i.e. Actor). But I'm not sure how to proceed. I'd rather not muck with the documentation format that others have defined, but it's an important goal to be able to just focus on "events" rather than all functionality defined or supported by a class. Any suggestions are welcome.

Areas

• Game Event Glossary
• Flowcharts?

About this page

This is going to be the home page for documentation on how the UnrealScript classes get called in the VM from the native engine code. It will probably always be imcomplete. But it should provide a good starting point for those who are trying to learn "what gets called when".

There are three objectives here:

1. Define important game events
2. Document UScript class entry points
3. Create flowcharts for important game event cycles

First, we'll try to define the set of "important" game events, such as game start, map change, player spawn, etc. These are not necessarily "events" in the UScript sense, but they are often related. These would simply be definitions of terms for reference in the other areas here.

Second, each of the methods in any classes (or derived classes) that are called directly by the engine would be documented on a per-class basis. This is a reference-style section, so you can look at a class and see what types of game events cause method calls for this class.

Note: Events should be documented in the "least derived class" for which they are relevant. Thus, events that are really designed for the UnrealPawn class should be documented there, not in Actor, nor in xPawn. This is a judgment call, but we should try to keep it as clear and intuitive as possible.

Third, something that I think would help tremendously in the learning process would be graphical flowcharts that show "game cycles" and how they work. So, for example, what happens when a player joins a game, or a projectile is fired? There are a number of key methods (listed in the above section) that are called, in a very specific order.

We don't need to get down to the microscopic source-level, as that would be redundant with reading the sources. But a high-level view of important processes in the game will be very useful.

Status

Just getting this started. I'll have the formatting guide for sub-pages laid out soon. -Laz

How to Contribute

If you want to contribute to this area, please add your name below and simply add your content to the pages. Please be careful about content, and if you believe someone else's information is wrong, please make sure to resolve it with them first before changing it.

If you don't want to deal with the Wiki directly, feel free to email any information or content to me and I will add it.

Lazarus (lazarus @ iforcemod.com)

Contributors

Lazarus

Comments?

Wormbo: Please concider using the existing structure of subpages. Actor/Methods and Object/Methods? would be much more suitable names IMHO.

Mychaeel: ...or Actor/Events and Object/Events? in this case. Nice work though. I can move the pages if you want.

Mychaeel: I just realized that Actor/Events exists and has a different purpose – but looking at it I think it could be safely deleted and replaced by what you're doing here.

Wormbo: I vote to keep Actor/Events because it describes a property group in UnrealEd just like e.g. Actor/Collision does. UnrealScript events are just methods after all.

Lazarus: But they're not really just methods, because they are initiated by the engine, as opposed to being called directly by a mod's code. I agree there may be a better way to integrate this documentation with the rest of the site, but the intent (as I just noted in the text above) is to keep it "event-specific".

I know this might be considered an artificial distinction from a certain point of view, but understanding event triggering (when and how) is extremely critical to being able to layout the foundation for a mod. It's easy to get lost in class documentation and "lose the thread" of event flow. That's why I wanted to do this.

It's possible the solution is to integrate some of the info in the subpages into the class documentation. As long as we can annotate which methods are event handlers, that would be fine. I just didn't want to start mucking about with everyone else's documentation. I figure I'll keep fleshing it out, and then we can merge what we need to in a way that makes sense.

Mychaeel: For now, moved the "FooClass Events" pages below UnrealScript Entry Points.