Liberi Developer Guide: Study

From EQUIS Lab Wiki

About

The Study class is a client-side class used for study-related operations. As of right now, it is used for writing study logs.

Logging

Study logs should not be confused with the normal client logs which show up in the Logs folder. Client logs are about the internal operations of the game client (like connections, device states, etc.), whereas study logs record real-time information like player location, heart rate and cadence. Study log entries can be one of two types: measures, and events. Measure entries are recorded regularly at a specified interval, whereas event entries are only recorded when certain game events occur. In addition, event entries also contain all the information that measure entries have. See the sections below for details.

Configuration

Part of the configuration for logging is done in the client scene of the Unity project. You will find a "study" object under the "client" object. The Study component allows you to specify a number of logging-related properties:

• MeasureLogInterval

The interval between each measure entry. Defaults to one second.

• LogDateFormat/LogTimeFormat

Format strings for dates and times which appear in logs or in the log filenames.

• LogHeaderColumns/LogColumns

String arrays specifying the column headings for the log header and body. These same properties also tell the Study class the order of values to write in all subsequent log entries.

The other configurable logging properties are in the Study.ini configuration file:

• LoggingEnabled

Whether or not study logs are written.

• LogPaths

A list of different log paths to write to. This is necessary because sometimes studies require multiple logs to be written (for example a synchronized one in Dropbox, and a local copy somewhere else). Log paths specified here can use special symbols to be replaced with special information. Specifically, they are:

• <p>: Player ID.
• <n>: Player nickname.
• <d>: Current date.
• <t>: Current time.

For example, a log path written as "Study Logs/<p>_<d>_<t>.dat" will end up looking something like this (depending on the player ID and time formats): "Study Logs/bobby_2014-08-19_18-03-35.dat".

• BalanceAlgorithm

Gross motor balancing algorithms implemented in Liberi. The following algorithms are currently available in Liberi:

• OneSpeedForAll: Pedaling is binary; if below minimum cadence then no movement, if above then gekku goes at full speed (in-game speed capped at 100%). The threshold is set in Controls by the MinPower attribute. Power is capped at 1, ie: Cadence / Cadence Cap cannot exceed 1.
• NoBalance: Linear relationship between pedaling cadence and gekku speed. Mapping of cadence to speed identical for all players. In-game speed is not capped, ie: Cadence / Cadence Cap can exceed 1 ( greater than 100% speed possible). The cap is the average (integer value) of a group's Ability Balance cadence caps.
• AbilityBalance: Logarithmic relation ( log(4)[3 * power + 1] == 1 / log(3 * power + 1)[4] ) between pedaling cadence and gekku speed, speed capped at a cadence tailored individually to players, based on GMFM score?

• GMFStudy

Gross motor function study is being run. Limits player movement to Y-axis only in Gekku Race when set to true. Only works as intended with gamepad controls on client.

• Autopilot

Moves player moves upward at a constant speed in Gekku Race when set to true.

• NoShooting

Disables skill use (shooting) in Gekku Race when set to true.

• AimingStudy

Aiming study is being run. Allows omni-directional (360°) shooting.

• aim_assist

Aim assistance in Gekku Race. Fire vector is adjusted to hit the closest target in range. The range and area of aim assistance correction is determined by a collider on the avatar pointer prefab..

Measures

Measures are regularly logged pieces of information about the game. The Study class determines which measures to write in each entry using the LogHeaderColumns and LogColumns properties. For each column heading, the Study class finds the corresponding "column value provider" method inside the Scripts/Core/Study.LogColumnValues.cs file. This method is then invoked every time a log entry is written, in order to fetch the most up-to-date value for its column. For example, the "Avatar Position" column will always be filled by the GetAvatarPositionColumnValue method, and the "Heart Rate" column will always be filled by the GetHeartRateColumnValue method, and so forth. If you ever need to add a new column to the logs, simply write a new provider method in Scripts/Core/Study.LogColumnValues.cs, and then add the column heading to the "study" object in the client scene.

Events

Log events are explicitly logged when certain things happen. e.g., the player pressed a button, or entered a new zone, or obtained an item. Each log event consists of an event "type", and any number of "arguments". For example, Gekku Race could have its own event type for rounds finishing, in which case possible arguments could be the winner of the round, and the duration of the round. You as the developer can create new log event types by creating a new enumeration under Scripts/Log Events, and then using the LogEvent attribute on its value declarations. Consider the following example, using Scripts/Log Events/GekkuRaceLogEvent.cs:

public enum GekkuRaceLogEvent
{
    [LogEvent("Target")]
    Hit,
    [LogEvent("Source")]
    HitBy,
    [LogEvent("Winner", "RoundTime:0.0")]
    RoundFinish
}

The enumeration serves as a kind of event category, with each of its values representing one specific type of Gekku Race event. Here, we have events for when the local player hits or is hit by another player, and when the round finishes. Notice how each enumerated value has the LogEvent attribute attached to it, which can also specify any number of arguments. e.g., the "Hit" event type has a "Target" argument, which presumably would indicate the player that was hit by our attack. To write a Gekku Race event to the log, we can simply call something like this from any Gekku Race-related script:

Study.LogEvent(GekkuRaceLogEvent.RoundFinish, winner, roundTime);

The method will look at the event type passed in, and figure out how to interpret the subsequent arguments. This log event entry would show up in the log like this:

GekkuRace.RoundFinish: { Winner=bobby, RoundTime=354.8 }

Notice that the -LogEvent suffix of the enumeration name has been omitted for aesthetic purposes. Also notice that any event parameter can be formatted by specifying a format string after its name in the LogEvent attribute. For example, the "RoundTime" argument above is formatted with "0.0".