Hook Light Engine: Game/Default File Information

The game/default file, tells the Hook Light Engine what output signals too watch out for. Then tied to the output signal, is light controller number(s), with group number(s), and a command with it’s arguments. There can be multiple light controllers used, but they have to be on their own line. Like the Light gun DefaultLG game file, that uses output signal, player, and command. The light controller game/default file uses output signal, light controller and group(s), and command. In the file, empty lines can be anywhere. Also, if the line doesn’t start with ‘:’, ‘!’, or ‘>’, it is ignored. So a user can put notes into the file on any line, as long as the line doesn’t start with the 3 characters. The game/default file is a simple text file (.txt). Just make sure that the 3 characters are at the front of the line, or they will not work.

Multiple Default files can be used with Hook of the Reaper. So the user can have different display effects happen, when they load another game. This is done by numbering the Default files starting with 0 (default0.txt), and incrementing from there. There must be at least 2 numbered default files (default0.txt & default1.txt) for it to work. The numbered default files are scanned when Hook of the Reaper is started. If changes are made to the files, Hook of the Reaper must be re-started. Also, the number of the next number Default file that will be loaded is kept in the ‘lcIndexData.txt’ file, in the ‘lightFiles’ directory. This is because of game drives that close Hook of the Reaper after the game has been ended. Since Hook of the Reaper is open and closed, it is the only way for Hook of the Reaper to keep track. If you just want to use one Default file, then just use 'default.txt', with no numbers.

The game/default file has 6 simple rules. Two of the rules are how the file starts and how it ends. The next three rules, are what can come after the 3 options in the group/default file. The last rule is too make sure that a light controller and group, is not used twice on the same output signal. If these rules are followed, then there is no problem with the file. Please note, that the rules only apply to the lines that start with the 3 characters. Everything else is ignored by the Hook Light Engine.

Rules

1. The game/default file must start with an output signal (:).
2. From the output signal (:), it can go to another output signal (:) or light controller and group(s) (!). It cannot go to a command (>).
3. From the light controller and group(s) (!), it can go to another light controller and group(s) (!) or a command (>). It cannot go to an output signal (:).
4. From the command (>), it can go to an output signal (:) or light controller and group(s) (!). It cannot go to a command (>).
5. The game/default file must end with an output signal (:) or a command (>). It cannot end in a light controller and group(s) (!).
6. The same light controller and group(s) (!), cannot be used twice on the same output signal (:), unless one of the commands is a background command, like Background or Display Range.

When a game is started in HOTR, the Hook Light will first check if there are any light controllers. If there are no light controllers, it does nothing. If there is a light controller, then Hook Light will look for the game file in the ‘lightFiles’ directory. If it cannot find the game file, then it will look for a default file (default.txt) in the same directory. If there is no default file, then it will do nothing.

If a light command is being executed, while another command comes in using the same pin(s) or strips, then the new command that will be blocked and not executed, unless it is a special case. For example, let’s say player 1 reloads, and has the green sequence of lights command started. Right after the reload, player 1 gets damaged, and causes a red flash light command on the same pins as the reload. Then the red flash light command will be blocked. This is too stop commands on the same pin(s) or strip running together. If not, then the red flash light command will happen along with the reload, and look bad. The light controller checks the pins on the new command, and if 1 pin is being used for the new command, it will be blocked. So pay special attention to your groups of pins. This only happens to commands that use timers. Commands that don’t use timers, like the Followers command, will not be blocked. There is a special case for LED Hook: Strip Flash commands, which have the Wait argument. If the Wait is enabled with a '1' and the strip(s) are being used by an older command, the command will be buffered, until the strip(s) come available.

The commands can be separated into 2 categories. The first category are commands that use timers. These are the Flash, Sequence, and Slash commands. Or any command that you have to put a time argument into. These commands use a non-blocking delay. Meaning, when the delay is running, the light controller can do other things, like run different commands for other players. The timer uses multiple delays for each command. For the time on and off for Flash commands. And the time delay in the Sequence and Slash commands. Because of this delay, it blocks a new command that uses the same pin(s) or strip. This is to make sure that the command is not interrupted while running. If you want to limit the blocking, that make the time of the delays as small as possible. The best is to have short light commands for game play. Other commands, like the 'Death' command, could be longer without worry of being ignored, as recoil or damage cannot happen until the player starts again.

The second category are commands that don’t use a timer. These are the Follower commands. These commands follow the output signal’s value. If the value is 0, then the light is turned off. If the value is greater than 0, then the light is turned on. Since it is simple command, it doesn’t use a timer. This is very similar to how MameHooker light control worked. Since there is no timer, the light controller doesn’t block the signal. So it can overlap with a command that uses a timer. So be careful on how you set-up your groups and pins.

Also, the commands be separated into 2 categories again. The first category is regular light commands. Regular lights are usually white lights in a color container, like a button. For example, player 1’s lights are blue buttons, and will light up blue when turned on. Then player 2’s lights are red buttons, and will light up red when turned on. The regular command will have ‘Regular’ in the command name. The second category is the RGB light commands. This is were a light has 3 lights, that are red, blue, and green. Which are the 3 primary colors, and can be combined to make many other colors, using the intensity of each light. These command need a color that has been defined in the group file. The RGB commands will have ‘RGB’ in the command name.

There are 3 things that the file needs to run a display function. The first is the output signal, which can be tied to light controller(s) & group(s), and a command. Or it can be just an empty output signal. Empty output signals can be used, but discourage in the file. The second thing needed is the light controller and group(s). There can be multiple non-matching light controllers used. Non-matching means that you cannot re-use the light controller in a different light controller line, attached to an output signal. So, you cannot use light controller !0 with group 1, two times on 2 different lines after the output signal. The last thing needed is the command that will be executed, when the output signals data meets the requirement. Each command will have it’s own arguments and requirements. These will be detailed later in this file.

Output signals have a ‘:’ in front of them, and needs to be at the front of the line. See an example below.

The output signal's value can be inverted. This is done by putting a '~' right after the output signal's name, with no space. Then, if the value is 0, it will be changed to a 1. If the value is 1 or more, then it will be a 0. Please see below to see an example of this inversion.

Light Controller and Groups have a ‘!’ in front of them, and need to be at the front of the line. See an example below. The first light controller entered is light controller 0. You can see there number by opening the ‘Edit Light Controller’ window. In the combo box, it will have a list of the light controllers, starting with their number. That number is used right after the ‘!’ symbol. Then after the light controller’s number, has to be at least 1 group number. Multiple groups can be used and need to be separated by a space. See an example below, where light controller 0 is used, with groups 0, 2, and 4.

The controller number is next to the ‘!’ symbol. Then the number(s) after are the group(s). There must be a group number, or the file will error out. Multiple controllers can be used, but need to be on their own line. See an example below.

The light controller can be used multiple times, as long as it has different groups. This is highly discouraged, as it is very non-efficient. If a light controller is being used, it is highly advised to put on the groups into one line. This will help out the Hook Light Engine.

Will work, but should be.

Commands have a ‘>’ in front of them, and need to be at the front of the line. There are 11 commands for Ultimarc RGB lights. Then there is 8 commands for Ultimarc regular lights. There is 4 commands for the LED Hook: Strip lights. The one command in RGB, and not Regular, is the Follower Random command. This RGB command does a random color. Where the Regular command would do a random intensity, which wouldn’t look good, So I took it out. Every command is detailed in the Ultimarc Commands and LED Hook: Striip Commands.

If there are different commands needed for an output, because of multiple different light controllers. Then after the first command, the new command’s light controllers and groups/strips are put into their on lines. Then followed after is the new command. Below is an example of using Ultimarc device command, with an LED Hook: Strip command after it, using the same output signal.

Also, you can seperate these two commands, if the user wants to. Both will work in the game/default file. If you wanted to keep the Ultimarc and LED Hook: Strip commands seperated, then this can be used. Please see the example below for this.

As you can see, it is simple to use different light controllers, and their commands, with an output signal. The hard part is keeping track of the controllers and the groups/strips. It is good to pt in notes in the files, to keep things organized.

Also, a light controller can be used multiple times, if the groups are different. For example, when output signal P1_Damaged goes high, you want light controller 0 and group 0 to flash, and light controller 0 and group 1 to do a sequential. Please see below on how to do that.

Now the light controller can do multiple commands, as long as it is different groups, and the groups don't have the same pin(s) or strip. If they do have the same pin(s) or strip, then the 2nd command will not be executed. As Hook Light Engine will see that the pin(s) are already in use. This is the users responsibility.

In the example above, if light controller 0 and group 0 was used twice, it would error out. This is due to the 6th rule. This is because the 2nd command will never run, as it is running the 1st command on the group. To make sure users don't do this, I put in the rule and check. Please see the failing example below.

The exception for this, if one of the commands is the Background or Display Range command. This is because these commands run in the background, and normal commands can run on top of them. Because of this, these commands shouldn't be counted as a command in this rule. Will be put into HOTR v1.3.3.