-
Notifications
You must be signed in to change notification settings - Fork 2
Core Concepts
Core terms:
| Term | Explanation |
|---|---|
| Game Controller | A prim in a level that contains all the code that controls the level. In the obstacle course levels it's the "Join Game" pad. |
| Event | ObstacleScript is event driven, everything happens in the event block. |
| Method | A way of sending data from one script to another, including inter-linkset. |
| Module | A script that's using the ObstacleScript event handler |
| Asset | An object spawned in a level |
| Portal | A script that links Assets with the level |
| HUD | The XOBJ HUD |
| Level DB | In SL database that stores information on where/how Assets should spawn. |
| Spread | Many function definitions use a "spread" type, which is just a fancy way of saying that they take a vaiable number of arguments joined by a + symbol. For an instance, the third argument of runMethod is a spread. So if you did: runMethod("TargetScriptUUID", "TargetScriptName", "Argument 1" + "Argument 2"), then "Argument 1" and "Argument 2" are sent as separate arguments that can be captured with argStr(0) and argStr(1), and not as "Argument 1Argument 2" as you'd expect when combining strings with + |
The library is split into the following sections:
These are files stored directly in the root directory, such as index.lsl, begin.lsl, and end.lsl. These contain macros and definitions that affect the entire framework. Such as the definition of runMethod.
Header files live in /headers and use the file extension .lsh. There's nothing special about this extension, but it makes it easier in your editor to figure out if you're working on a header file or module file. Headers contain event/method definitions, and macros to make using these events and methods easier. All the headers in the main project are included in index.lsl, so you don't need to worry about including them manually.
Modules are files that contain the actual code. They should generally have one job, which should be defined in the header. Such as the Gui module should handle the user interface on your HUD, and the Interact module should handle the E to interact things for the HUD.
For more info about what makes up an ObstacleScript module, see Module Dissection
Local are event bindings for built in LSL events, and custom ObstacleScript overrides for these. Such as timer(){} being replaced by a better one that lets you set intervals, timeouts, and control many timers at once. Or the listen handler which also handles Method communication between scripts.
Resources are macro "packages" that are there to simplify level creation. For an instance, if you don't want to write your own dialog manager for the Level Controller, you can use templates in DialogHelper. It also contains useful functions and macros like teleporting all players in a ring etc.
These are custom headers for specific obstacles, detailing what channel they communicate on and what syntax messages they use. Most obstacles use a short direct way of communicating by passing JSON lists directly through llRegionSay to, since it's faster than using standard methods.
The HUD is mostly used as an RLV relay, visual effects, and quick time events. The gameplay is controlled by the level controller.
- The pink bar in the obstacle courses are created by the level going "Create a bar with this color, and set the percentage value to this". It's just a visual effect and the HUD doesn't have any information of what the HUD does or not.
Methods are a way of communicating with a specific script directly. Methods are called through the runMethod function, but are usually abstracted away in header files to easy to use macros such as Rlv$exitMouselook( target ). Methods can be run either within a linkset, or between objects.
Unlike methods, events can be captured by every script in a linkset. They're raised internally within the linkset. In order to have an external script raise a method you need to do that through an external input such as a method or built in event. The standard SL events are also events.
ObstacleScript events are raised by using raiseEvent, and can be captured through an if statement (commonly you'd make event handler macros).
For an instance you could manually use: handleEvent( "Level", LevelEvt$mainMenu ) ...code... end, or use the built in macro onLevelMainMenu() ...code... end
Since ObstacleScript wraps everything between two includes, using one singular event handler. You can't add the default event handlers the normal way of ex: touch_start( integer total ){}, but you have to make a define at the start of the script that you want to use it. Ex: #define USE_TOUCH_START. This allows you to use the ObstacleScript event handler onTouchStart( total ) ...code... end
See a list of implemented LSL events here.
The level uses a standard LSL prim media DB to store a table of assets. After setting up the scripts, you can save any rezzed Assets to the DB by saying SAVE. The DB allows you to store:
- Name of object
- Position relative to root
- Rotation relative to root
- Description
- Spawn label
The first 3 are just used in rezzing.
The description can be read by the Asset after spawning and initializing. Usually this is a JSON array allowing you to configure the object. Such as setting up keyframes where a trapdoor should move, or how far a crusher wall should move.
The spawn label allows you to group assets to rez. An empty spawn label "" is the default, and used for any objects that should spawn initially. Note that the obstacle courses only use "" as all obstacles should be spawned at once. But this could be used if you wanted to make a linear stage where things spawn as the players advance.
To see a list of commands to interact with the DB, check the main page.
An asset is considered an item that's spawned by the level. These all rely on the Portal script to link them to the level database.
The core philosophy of xMod is that the level controller (the board that controls the game) should have as much control over the gameplay as possible. Usually the Assets (such as the obstacle course obstacles) will take commands from this central controller, and/or send events to the main controller when something happens.
- The crusher walls in the obstacle course levels won't move on their own. The level controller tells them when they should move, and their description tells them how they should move.
- The wall tentacles send a message to the level controller when someone collides with them. The level then tells the tentacle to grapple that player.
Exceptions can be used when an item needs as quick of a reaction time as possible, or when offloading their behavior to the level controller would eat too much script memory (such as the shimmy walls).
Some assets are auto loaded from the HUD. If you want to change a behavior of a built in asset, make your changes and rename it before putting it back into the Level Controller.
Items can be injected into the players HUDs by the level controller, such as the balloon attachment. You do this by placing them into the Level Controller, and when a player joins, the attachment gets injected into their HUD. Caveats:
- The injected asset must be full perm.
- The inject asset's name must start with
HUD: