Developer Guide

From Hopmod Wiki

Contents 1 Source Tree Overview 2 Naming Conventions 2.1 Module Variables 2.2 Inconsistencies 3 General Coding Standards 4 Execution Model 5 The Server Table 6 Player Identification Methods 6.1 By Client Number (CN) 6.2 By Session Number 6.3 By ID Number 6.4 By IP Address 6.5 By Name 7 Player Command Security 8 Message Colour Formatting 9 Module System 9.1 The Module Command 9.2 Search Paths 9.3 Module Variables

Source Tree Overview

• /script - Lua code,
  • /base - Basic stuff,
    • init.cs - The first script to be executed by the core game server at initialization,
    • init.lua - The first Lua script to be executed,
    • resetvars.cs - Where variables for the required modules are declared
  • /command - Player command scripts,
    • _bindings.lua - Player command registrations,
  • /module - All the add-on modules,
    • /auth - Player authentication modules,
    • /balance - Managing the balance for things such as team balance or readjusting the server capacity based on the number of spectators,
    • /declare - Where variables for any module are declared and initialized with default values,
    • /detect - Modules for detecting player behaviour,
    • /display - Modules whose main purpose is to display messages for players,
    • /gamemode - Modules that change server configuration in specific game modes,
    • /limit - Modules to limit player-related things like team killing, idle time and ping etc,
    • /override - Override normal behaviour for a range of things,
  • /package - Third-party Lua modules,
• /src - C++ code,
  • /fpsgame,
    • server.cpp - Core game server source file,
  • /hopmod,
    • extserver.cpp - Extended source code included into ../fpsgame/server.cpp,
    • script_bindings.cpp - Where functions and variables are defined in the core game server are bound to the scripting environment,
    • signals.cpp - Signal/event definitions and bindings,
    • startup.cpp - Where Lua modules for Hopmod are registered

Naming Conventions

• Separate words with underscore,
• Variables in lowercase,
• Constants in uppercase,
• Use clear names (don't abbreviate),
• Don't use get prefix on getter functions (e.g. server.player_frags(), not server.get_player_frags())

Module Variables

• Prefix with the module name

Inconsistencies

You'll notice that there are inconsistencies in the names used. Lua's standard library and Cube 2 use a slightly different naming convention to Hopmod, they tend not to separate words (e.g. tostring(), instead of to_string()). Many of the Hopmod modules use an internal convention for their private functions and variables, many use camel case convention.

General Coding Standards

• Use 4 spaces to ident your code (don't use tabs),
• Lua Style Guide

Execution Model

The server executes from two points: when packets are received and at a regular interval (~5ms); the interval is used to update things like game state, check for connection timeouts, and to poll for some services. Hopmod extends the core game server with an event system to simplify the execution model. Most script code is run from event handlers. Nothing is ever run in parallel at the process level; the process is single-threaded. You don't have to worry about event handlers overlapping in execution; when the control flow is in your event handler nothing else is running and the server is depending on the handler to return as soon as possible.

The Server Table

All the functions and variables of the core game server (the host app) are exposed to the Lua environment through the server table. It's possible to extend the server table with Lua functions; think of it as a namespace for public functions and variables. The server table has a metatable (used to alter the behavior of the table) that interacts with the core game server; when something is added it also gets passed to the Cubescript environment. Everything on the server table is accessible from the script pipe and script socket services (they use Cubescript), meaning for example that you could write a function in Lua and then call it from the server shell. You could define a function in Cubescript (all global variables are passed to the server table in Lua) and then call it from Lua.

Player Identification Methods

By Client Number (CN)

A unique number assigned per player connection which is used by most of the player functions to address a player. The problem with using CNs is they will be reused on future connected players; for example, a player disconnects and then a connecting players is given their CN. It's a bad idea to use CNs when your script needs to address the same players across multiple events or in timer (sleep() or interval()) operations.

By Session Number

Function: server.player_sessionid(cn)

A randomly unique number assigned per player connection.

By ID Number

Function: server.player_id(cn)

The Player ID number is a unique number assigned to a unique name-ip pair. This form of ID is used by the stats module so stats data can be saved when the player disconnects and then the same data be re-associated to the player on reconnect. When a player reconnects with the same IP address and player name as before, the player ID number will be unchanged. Important note: If a player renames while connected a new ID is assigned. All ID numbers are erased on the maintenance event; with the default configuration, they will remain persistent for 24 hours.

By IP Address

Function: server.player_ip(cn) or server.player_iplong(cn)

Used by things where it's important that a player cannot simply rename or reconnect to escape their ID. The mute module mutes players by IP address; to circumvent the mute system a player would have to change their IP address (by reconnecting their net connection). The ban system is another example of identifying by IP.

By Name

Function: server.player_name(cn)

Player Command Security

When developing new player commands you have to consider what would happen if the player's input meant as a command was broadcasted. The fact is not all servers handle player commands so a player by mistake could send a command with private information on the wrong server where it would be broadcasted. Even on servers that intercept player commands you don't want players sending private information to foreign servers, it can potentially comprise player and your server security. Never create a player command that requires a password argument.

Message Colour Formatting

List of rules:

• Normal messages in white with the variable content highlighted in green,
• Error messages in all red,
• Game play messages in yellow with orange highlights,

Module System

All the extended functionality offered by Hopmod is decomposed as a collection of modules that can each be enabled or disabled. A module is simply a Lua script with an unload function defined, which is returned by the script in a table.

The Module Command

The purpose of the module command is to schedule the creation of a module instance; the command is invoked mainly from server.conf. To clarify, the module has not been started once the module command returns; modules are started later from a server "started" event handler.

The .lua file extension can be omitted from module names.

Search Paths

• <name>
• <name>.lua
• ./script/<name>
• ./script/<name>.lua
• ./conf/<name>
• ./conf/<name>.lua

Module Variables

Variables that are defined to allow the user to change the module configuration are declared in files located in /script/modvars; most of the variables for modules that are distributed with hopmod are declared in /script/modvars/all.vars. The syntax of these variable declaration files is Cubescript.