classes roomConfig - wxyz-abcd/node-haxball GitHub Wiki
This class defines a RoomConfig object to be used inside Haxball rooms. A RoomConfig is the backbone of all Haxball bots. Every room has an internal (and initially empty) RoomConfig object built inside.
Defines these functions that has to exist in every RoomConfig:
-
RoomConfig.prototype.defineMetadata(metadata: object): void
This function is called internally inside the constructor of all RoomConfigs by default. The function body is empty by default. This means that the
metadata
values are not stored in RoomConfig objects by default, because they are not useful in a non-GUI node.js environment. If we want to make use of themetadata
, we might override this behavior by overriding this method. Remember that this should be done after initializing the API and before initializing any RoomConfigs.Parameters:
-
metadata: object
: An object that holds some metadata values. This value might depend on what you want to do with this API. The examples in the GitHub repo are intended to be shown in a web application GUI that can be accessed by anyone. Therefore, they use the following structure for this object:-
name: string
: Name of the RoomConfig that will be displayed on the GUI. -
version: number
: The current version number of this RoomConfig. -
author: string
: The author of this RoomConfig. -
description: string
: A detailed description of this RoomConfig. -
allowFlags: int
: This value defines whether it is possible to use this RoomConfig while hosting or joining (or both) a room.
-
Return value: None.
Default definition (in node.js):
RoomConfig.prototype.defineMetadata = function(metadata){};
Example (default) definition (in a complex website):
RoomConfig.prototype.defineMetadata = function(metadata){ this.metadata = metadata; };
-
-
RoomConfig.prototype.defineVariable(variableObj: Variable): void
This function defines a variable inside the Addon object that can be changed from outside. If we want to make use of the metadata that we sent into this function, we can override this function. Only name and value fields are used by the default implementation. The implementation also depends on the API's global
config.noVariableValueChangeEvent
variable.Parameters:
-
variableObj: Variable
: An object that might hold some metadata values along with the variable's name and value. This object might depend on what you want to do with this API. The examples in the GitHub repo are intended to be shown in a web application GUI that can be accessed by anyone. Therefore, the following structure is used for this object:-
name: string
: Name of the variable. -
value: any
: The default/initial value of this variable. -
type: VariableType
: Type of this variable. (omittable) -
description: string
: A detailed description of this variable. (omittable) -
range: object
: The possible range of this variable's value. Should only be applied to numbers(literally) and maybe strings(for min and max length of the string). (omittable)-
min: number
: The minimum value for this variable. (omittable) -
max: number
: The maximum value for this variable. (omittable) -
step: number
: The step increment/decrement for this variable. (for easy increment/decrement via a spinbox) (omittable)
-
-
Return value: The initial value of this variable.
Example (default) definition (in a complex website):
RoomConfig.prototype.defineMetadata = function(metadata){ //...do other stuff... this.variables = {}; // define an object that will hold all variable details inside all RoomConfigs. }; var originalDefineVariable = RoomConfig.prototype.defineVariable; RoomConfig.prototype.defineVariable = function(variable){ //...do other stuff... originalDefineVariable(variable); this.variables[variable.name] = { // store all variable details inside all RoomConfigs, so that you can show them later in your GUI application if you want to. type: variable.type, range: variable.range, description: variable.description }; //...do other stuff... };
-
Creates a new RoomConfig
instance.
-
metadata: object
: Any information that we would want to show/update inside a GUI application about this RoomConfig. This is not used by the API by default, but we can reprogram the RoomConfig's prototype to make use of this value if we want. (For instructions, see section 1.)
Example RoomConfig definition:
// If you are using require.js library or in node.js,
// API might also be defined via var API = require("node-haxball");
function TestRoomConfig(API){
const { RoomConfig } = API;
Object.setPrototypeOf(this, RoomConfig.prototype);
RoomConfig.call(this, { // this is the call to the constructor.
version: "0.1",
author: "author",
description: `This is a test roomConfig`
});
// Custom RoomConfig codes here...
}
-
room: Room
: The Room object that this RoomConfig is attached to.
The API can work with the following callback functions inside a RoomConfig
object.
-
initialize(): void
If defined, called while creating or joining a room, or during a call to
Room.setConfig
. You should write all custom initialization logic inside this callback function.Parameters: None
Return value: void
-
finalize(): void
If defined, called while leaving a room, or during a call to
Room.setConfig
. We should write all custom finalization logic inside this callback function.Parameters: None
Return value: void
-
Common Callbacks
A RoomConfig calls all common callbacks by prepending
onBefore
,on
, andonAfter
before the callback's name. As an example; if the common callback isRoomPropertiesChange(props: object)
, there are 3 different callbacks related to it in the RoomConfig class:-
customData = onBeforeRoomPropertiesChange(props: object)
: This is called as soon as the event happens at first, before all plugin and renderer callbacks for the same event. We can use this to initialize acustomData
object and return it from the function. The customData object is automatically passed to the next callback for the same event. -
customData = onRoomPropertiesChange(props: object, customData: object)
: This is called just before the other plugin and renderer callbacks for the same event. -
customData = onAfterRoomPropertiesChange(props: object, customData: object)
: This is called in the end, after all plugin and renderer callbacks for the same event have finished running.
We have to select the callbacks that we want to use and transform the callback signature to one of the above depending on when we want it to run while defining them in our RoomConfig. All of these callbacks may also take an extra
customData
parameter that is passed from the previously called callback and may also return a new customData object to the next callback in the callback queue. This is done to be able to better communicate between API components.NOTE: To use the modifier callbacks(except
onOperationReceived
, which is just like the other callbacks) in RoomConfig classes, we do not prependonBefore
,on
, andonAfter
. Instead, we appendBefore
, nothing andAfter
. Thebefore
callback has to return an array with two objects, the last one being thecustomData
. So for example, the modifier callbacknewFrameNo = modifyFrameNo(frameNo: int)
has 3 callbacks in a RoomConfig:[newFrameNo, customData] = modifyFrameNoBefore(frameNo: int)
,newFrameNo = modifyFrameNo(frameNo: int, customData: any)
andnewFrameNo = modifyFrameNoAfter(frameNo: int, customData: any)
.NOTE: All callbacks are also accessible through all room objects directly. For example; we can write the code to add an
onRoomPropertiesChange
callback to room's config in two different ways:-
Inside a RoomConfig:
this.onRoomPropertiesChange = function(props, customData){ // callback code here... // return customData; // you can return whatever you want here }
-
By modifying the RoomConfig inside a Room object indirectly:
room.onRoomPropertiesChange = function(props, customData){ // callback code here... // return customData; // if you need it }
You can see the complete list of common callbacks here.
-