Next: , Previous: , Up: C API   [Contents][Index]


5.37 libpil

5.37.1 Overview

View lcov test coverage results on http://www.ufoot.org/liquidwar/v6/doc/coverage/src/lib/pil/index.html.

5.37.2 API

Function: int lw6pil_bench (lw6sys_context_t * sys_context, int argc, const char * [] argv, float * bench_result, lw6sys_progress_t * progress)

sys_context: global system context

argc: number of args as passed to main

argv: args passed to main

bench_result: pointer to float, will contain the bench result

progress: to inform the caller of the process advancement

Runs a standard, normalized bench on a default map. Results can be interpreted as an estimated speed/power of your computer.

Return value: 1 on success, 0 if failure

Function: lw6pil_command_t * lw6pil_command_new (lw6sys_context_t * sys_context, const char * command_text, int64_t seq_0, int round_0)

sys_context: global system context

command_text: readable text of the command

seq_0: sequence offset reference (to calculate difference between sequence and rounds)

round_0: round offset reference (to calculate difference between sequence and rounds)

Creates a new command from its text representation.

Return value: newly allocated object

Function: lw6pil_command_t * lw6pil_command_dup (lw6sys_context_t * sys_context, lw6pil_command_t * command)

sys_context: global system context

command: object to duplicate

Creates a copy of a command struct.

Return value: newly allocated object.

Function: void lw6pil_command_free (lw6sys_context_t * sys_context, lw6pil_command_t * command)

sys_context: global system context

command: command to free

Frees a command struct, with all its members.

Return value: none.

Function: char * lw6pil_command_repr (lw6sys_context_t * sys_context, const lw6pil_command_t * command)

sys_context: global system context

command: command to represent

Gives a readable representation of a command.

Return value: dynamically allocated string.

Function: int lw6pil_command_execute (lw6sys_context_t * sys_context, lw6pil_dump_t * dump, int64_t timestamp, lw6ker_game_state_t * game_state, lw6pil_command_t * command)

sys_context: global system context

dump: pointer on dump structure (out param, can be NULL)

timestamp: current timestamp (can be 0 if dump is NULL)

game_state: game state to work on, can be NULL (usefull for DUMP)

command: command to process

Interprets a command and runs it against game_state. If dump and timestamp are set, then any DUMP command will fill the dump structure with the right values. If not running from a pilot context, this is useless, use NULL and 0LL.

Return value: 1 if ok, 0 if failed.

Function: int lw6pil_command_execute_text (lw6sys_context_t * sys_context, lw6pil_dump_t * dump, int64_t timestamp, lw6ker_game_state_t * game_state, const char * command_text, int64_t seq_0)

sys_context: global system context

dump: pointer on dump structure (out param, can be NULL)

timestamp: current timestamp (can be 0 if dump is NULL)

game_state: game state to work on, can be NULL (typically for DUMP)

command_text: command text to process

seq_0: reference seq_0, used to genereate consistent dumps if needed

Interprets a command text and runs it against game_state. If dump and timestamp are set, then any DUMP command will fill the dump structure with the right values. If not running from a pilot context, this is useless, use NULL and 0LL.

Return value: 1 if ok, 0 if failed.

Function: int lw6pil_command_execute_local (lw6sys_context_t * sys_context, lw6pil_local_cursors_t * local_cursors, lw6pil_command_t * command)

sys_context: global system context

local_cursors: local cursors information

command: command to execute

Executes a local command, typically a cursor move, on the local_cursor struct, without changing any game state.

Return value: 1 if success, 0 if failure.

Function: int lw6pil_command_execute_local_text (lw6sys_context_t * sys_context, lw6pil_local_cursors_t * local_cursors, const char * command_text)

sys_context: global system context

local_cursors: local cursors information

command_text: command text to execute

Executes a local command text, typically a cursor move, on the local_cursor struct, without changing any game state.

Return value: 1 if success, 0 if failure.

Function: void lw6pil_coords_fix (lw6sys_context_t * sys_context, lw6map_rules_t * rules, lw6sys_whd_t * shape, float * x, float * y, float * z)

sys_context: global system context

rules: the set of rules to use (defines polarity)

shape: the shape of the map (logical part)

x: the x coord to fix

y: the y coord to fix

z: the z coord to fix

Similar to lw6map_coords_fix but using floats, this function can be used to check cursor position boundaries. Any float pointer can be NULL.

Return value: none.

Function: void lw6pil_coords_fix_x10 (lw6sys_context_t * sys_context, lw6map_rules_t * rules, lw6sys_whd_t * shape, float * x, float * y, float * z)

sys_context: global system context

rules: the set of rules to use (defines polarity)

shape: the shape of the map (logical part)

x: the x coord to fix

y: the y coord to fix

z: the z coord to fix

Similar to lw6pil_coords_fix but does use a wider range, say 10 times the actual size of the map, this is not to contain the cursor within the map but just to avoid overflow errors.

Return value: none.

Function: void lw6pil_dump_zero (lw6sys_context_t * sys_context, lw6pil_dump_t * dump)

sys_context: global system context

dump: object to initialize

Fills a dump object with zero, regardless of what was there before.

Return value: none.

Function: void lw6pil_dump_clear (lw6sys_context_t * sys_context, lw6pil_dump_t * dump)

sys_context: global system context

dump: object to clear

Clears a dump object, that is, frees all existing object if they are here, and sets pointers to NULL.

Return value: none.

Function: int lw6pil_dump_exists (lw6sys_context_t * sys_context, const lw6pil_dump_t * dump)

sys_context: global system context

dump: object to test

Tests wether there’s actually a dump in the structure, or if it’s empty.

Return value: 1 if there’s a dump, 0 if all fields set to NULL.

Function: char * lw6pil_dump_command_generate (lw6sys_context_t * sys_context, lw6pil_pilot_t * pilot, u_int64_t server_id, int64_t seq)

sys_context: global system context

pilot: the pilot to transform as a DUMP.

server_id: ID of server issuing the command

seq: seq at which the dump should be generated

Creates the DUMP command for a given pilot, that is, a command that describes the whole data and state. One must give a sequence number since the dump would otherwise typically be *always* late by at least one round (or seq). We give the seq as we would for any message generated, to make it fit well within the standard message queue.

Return value: newly allocated string

Function: int lw6pil_dump_command_execute (lw6sys_context_t * sys_context, lw6pil_dump_t * dump, int64_t timestamp, lw6pil_command_t * command, lw6sys_progress_t * progress)

sys_context: global system context

dump: will contain the dump data, pilot and game state, struct, and level

timestamp: current timestamp

command: the command to execute

progress: progress object to show the advancement of process

Interprets a DUMP command. A new pilot will be returned, along with game state, game struct and level. Old objects won’t be deleted, but you could (should) get rid of them at they are useless now.

Return value: newly allocated string

Function: void lw6pil_local_cursors_reset (lw6sys_context_t * sys_context, lw6pil_local_cursors_t * local_cursors)

sys_context: global system context

local_cursors: the structure to reset

Resets a local cursors struct. Note that this need not be called very often, in fact the local cursors can cope with "dead" cursors easily. In practise, in a local game, there are only 4 of them, great maximum.

Return value: none.

Function: lw6pil_local_cursor_t * lw6pil_local_cursors_get_cursor (lw6sys_context_t * sys_context, lw6pil_local_cursors_t * local_cursors, u_int16_t cursor_id)

sys_context: global system context

local_cursors: the structure to query

cursor_id: the id of the cursor to query

Returns a pointer on the cursor with the given id.

Return value: a pointer (must *not* be freed) which is NULL is cursor does not exist.

Function: int lw6pil_local_cursors_get_info (lw6sys_context_t * sys_context, lw6pil_local_cursors_t * local_cursors, int * x, int * y, int * mouse_controlled, u_int16_t cursor_id)

local_cursors: the structure to query

x: a pointer to the x position, may be NULL

y: a pointer to the y position, may be NULL

mouse_controlled: a pointer to the mouse_controlled flag, may be NULL

cursor_id: the id of the cursor to query

Gets the x,y position of the cursor, and tells if it’s mouse controlled.

Return value: 1 on success (cursor exists), 0 on failure (no such cursor).

Function: int lw6pil_local_cursors_set_xy (lw6sys_context_t * sys_context, lw6pil_local_cursors_t * local_cursors, u_int16_t cursor_id, int x, int y)

sys_context: global system context

local_cursors: the structure to modify

cursor_id: the id of the cursor to modify

x: the x position

y: the y position

Sets the position of a cursor in the local cursors struct. If cursor does not exists, it’s appended to the list.

Return value: 1 on success (cursor exists), 0 on failure (no such cursor).

Function: int lw6pil_local_cursors_set_mouse_controlled (lw6sys_context_t * sys_context, lw6pil_local_cursors_t * local_cursors, u_int16_t cursor_id, int mouse_controlled)

sys_context: global system context

local_cursors: the structure to modify

cursor_id: the id of the cursor to modify

mouse_controlled: the mouse_controlled attribute

Sets which cursor is mouse controlled. If mouse_controlled is 1, the flag is set for this cursor and cleared for all others. If set to 0, only this cursor’s flag is cleared.

Return value: 1 on success (cursor exists), 0 on failure (no such cursor).

Function: int lw6pil_local_cursors_get_main_info (lw6sys_context_t * sys_context, lw6pil_local_cursors_t * local_cursors, u_int16_t * cursor_id, int * x, int * y, int * mouse_controlled)

sys_context: global system context

local_cursors: the structure to query

cursor_id: the id of the main cursor, may be NULL

x: a pointer to the x position, may be NULL

y: a pointer to the y position, may be NULL

mouse_controlled: a pointer to the mouse_controlled flag, may be NULL

Gets the x,y position of the main cursor, and tells if it’s mouse controlled.

Return value: 1 on success (cursor exists), 0 on failure (no such cursor).

Function: int lw6pil_local_cursors_set_main (lw6sys_context_t * sys_context, lw6pil_local_cursors_t * local_cursors, u_int16_t cursor_id)

sys_context: global system context

local_cursors: the structure to modify

cursor_id: the id of the cursor to be labelled as main cursor

Sets the main cursor attribute, the main cursor is later used, for instance, to decide how to display the map (centered on it, for instance).

Return value: 1 on success (cursor exists), 0 on failure (no such cursor).

Function: int lw6pil_nopilot_poll_dump (lw6sys_context_t * sys_context, lw6pil_dump_t * dump, const char * command_text, int64_t timestamp)

sys_context: global system context

dump: will contain the dump information if needed, can be NULL

command_text: the command received from the network.

timestamp: timestamp, used to initialize the pilot

Normally, it’s the commit function of the pilot which will automatically return a dump if needed. But... when a client connects, at first, it has absolutely no pilot/map whatsoever yet, so this is just to bootstrap the process, this function will take network messages, any message, and if it’s about a dump -> it will create the dump.

Return value: 1 on success, 0 on failure.

Function: lw6pil_pilot_t * lw6pil_pilot_new (lw6sys_context_t * sys_context, lw6ker_game_state_t * game_state, int64_t seq_0, int64_t timestamp, lw6sys_progress_t * progress)

sys_context: global system context

game_state: the game state we’re going to work on

seq_0: the start sequence to use, that is, the seq at round=0

timestamp: the current ticks (1000 ticks per sec, used to calibrate)

progress: object used to show the advancement of the process

Initializes a ’pilot’ object, this object is responsible for interpreting messages, transform them into low-level ’ker’ module function calls, and handle all the thread-spooky stuff.

Return value: a working pilot object. May be NULL on memory failure.

Function: void lw6pil_pilot_free (lw6sys_context_t * sys_context, lw6pil_pilot_t * pilot)

sys_context: global system context

pilot: the object to free.

Frees a ’pilot’ object, note that this might involve joining some threads, so it can ’take some time’.

Return value: none.

Function: int lw6pil_pilot_send_command (lw6sys_context_t * sys_context, lw6pil_pilot_t * pilot, const char * command_text, int verified)

sys_context: global system context

pilot: the object to send commands to.

command_text: the text of the command, as received form network

verified: wether we’re sure this message is valid.

Sends a command and handles it internally.

Return value: 1 if OK, 0 if not.

Function: int lw6pil_pilot_local_command (lw6sys_context_t * sys_context, lw6pil_pilot_t * pilot, const char * command_text)

sys_context: global system context

pilot: the object to apply the local command on

command_text: the command text

This function is used to fix the annoying fact that by only sending commands a limited number of times per sec to the game state, the display always reflect an outdated position for cursors. But players do not want to see this, they want to see the cursor in the right place. So what we do is that the pilot can process "local" commands which have absolutely no effect on the game but simply update a local cursor state, only used for display. It’s here in the pil module for it’s where the command interpreting code is, and the fact that there’s this lag is directly linked with the pilot way of doing things.

Return value: 1 on success, 0 on failure.

Function: int lw6pil_pilot_commit (lw6sys_context_t * sys_context, lw6pil_dump_t * dump, lw6pil_pilot_t * pilot)

sys_context: global system context

dump: will contain the dump information if needed, can be NULL

pilot: the object to commit.

Commits all commands sent and actually send them to the corresponding threads. This commit system allows better performance by sending, for instance, all the commands for a given round together.

Return value: none.

Function: int lw6pil_pilot_make_backup (lw6sys_context_t * sys_context, lw6pil_pilot_t * pilot)

sys_context: global system context

pilot: the object to perform the backup on

Makes a new backup in the pilot, that is, copy ’reference’ to ’backup’.

Return value: 1 if OK, 0 if not.

Function: int lw6pil_pilot_can_sync (lw6sys_context_t * sys_context, lw6ker_game_state_t * target, lw6pil_pilot_t * pilot)

sys_context: global system context

target: the target game_state we would sync on

pilot: the object to perform the backup on

Tests wether sync functions are callable with a given game state. It verifies if the internal game_state and the target look the same.

Return value: 1 if sync functions can be called, 0 if not.

Function: int lw6pil_pilot_sync_from_backup (lw6sys_context_t * sys_context, lw6ker_game_state_t * target, lw6pil_pilot_t * pilot)

sys_context: global system context

target: the game_state structure which will get the informations.

pilot: the object to get informations from.

Gets the backup from the pilot object. This is the last snapshot taken by make_backup or, by default, the game_state the pilot was constructed with.

Return value: 1 if OK, 0 if not.

Function: int lw6pil_pilot_sync_from_reference (lw6sys_context_t * sys_context, lw6ker_game_state_t * target, lw6pil_pilot_t * pilot)

sys_context: global system context

target: the game_state structure which will get the informations.

pilot: the object to get informations from.

Gets the latest reference game_state, that is, a stable snapshot of the game, with no inconsistency, a game position that exists and that we can rely on. Note that getting this can take time since a global mutex is required, and computations must end before you get the data.

Return value: 1 if OK, 0 if not.

Function: int lw6pil_pilot_sync_from_draft (lw6sys_context_t * sys_context, lw6ker_game_state_t * target, lw6pil_pilot_t * pilot, int dirty_read)

sys_context: global system context

target: the game_state structure which will get the informations.

pilot: the object to get informations from.

dirty_read: wether to allow dirty read or not

Gets the informations from the pilot object, not being worried about game consistency, this one will just return the latest version available. It might even be in an inconsistent state, the position could reflect a position which will never exist. Still, the data returned will not correspond to a half-spread or half-moved game_state if dirty_read is set to 0. In this case the data has at least some basic consistency and getting this does require some mutex lock, however wait time should be fairly small (max. a round). But, in a general manner, this function is only used for display, and we do not care much if there’s a small glitch, we prefer fast & smooth display.

Return value: 1 if OK, 0 if not.

Function: lw6ker_game_state_t * lw6pil_pilot_dirty_read (lw6sys_context_t * sys_context, lw6pil_pilot_t * pilot)

sys_context: global system context

pilot: the object to get informations from.

Returns a direct access to the most up-to-date game_state, without locking anything whatsoever. This is clearly to implement a dirty read mode as the name of the function suggests.

Return value: 1 if OK, 0 if not.

Function: char * lw6pil_pilot_repr (lw6sys_context_t * sys_context, const lw6pil_pilot_t * pilot)

sys_context: global system context

Returns a string describing the pilot. This is a very short description, use it for logs, and to debug stuff. By no means it’s a complete exhaustive description. Still, the string returned should be unique.

Return value: a dynamically allocated string.

Function: void lw6pil_pilot_calibrate (lw6sys_context_t * sys_context, lw6pil_pilot_t * pilot, int64_t timestamp, int64_t seq)

sys_context: global system context

pilot: the object to calibrate

timestamp: the current ticks setting (1000 ticks per second)

seq: the round expected to be returned with this ticks value

Calibrates the pilot, that is, initializes it so that subsequent calls to lw6pil_pilot_get_round return consistent values.

Return value: none.

Function: void lw6pil_pilot_speed_up (lw6sys_context_t * sys_context, lw6pil_pilot_t * pilot, int seq_inc)

sys_context: global system context

pilot: the pilot to speed up

seq_inc: the number of seqs

Re-calibrates the pilot so that it speeds up a bit. This will basically increase next_seq by seq_inc.

Return value: none.

Function: void lw6pil_pilot_slow_down (lw6sys_context_t * sys_context, lw6pil_pilot_t * pilot, int seq_dec)

sys_context: global system context

pilot: the pilot to speed up

seq_dec: the number of seqs

Re-calibrates the pilot so that it slows down a bit. This will basically decrease next_seq by seq_inc.

Return value: none.

Function: int lw6pil_pilot_get_round_0 (lw6sys_context_t * sys_context, const lw6pil_pilot_t * pilot)

sys_context: global system context

pilot: pilot object to query

Get the initial round (the one passed at object construction) which says what the round was at object creation, it’s just an offset.

Return value: 64-bit integer

Function: int64_t lw6pil_pilot_get_seq_0 (lw6sys_context_t * sys_context, const lw6pil_pilot_t * pilot)

sys_context: global system context

pilot: pilot object to query

Get the initial seq (the one passed at object construction) which says what the seq was at round=0, it’s just an offset.

Return value: 64-bit integer

Function: int lw6pil_pilot_seq2round (lw6sys_context_t * sys_context, const lw6pil_pilot_t * pilot, int64_t seq)

sys_context: global system context

pilot: pilot object to work on

seq: the seq to convert

Converts a seq (64-bit) to a round (32-bit). 64-bit seqs are used to avoid out-of-range errors on very long games, OTOH a round is 32-bit to garantee the atomicity of its affection, even on platforms which are not native 64-bit.

Return value: the round (32-bit integer)

Function: int64_t lw6pil_pilot_round2seq (lw6sys_context_t * sys_context, const lw6pil_pilot_t * pilot, int round)

sys_context: global system context

pilot: pilot object to work on

round: the round to convert

Converts a round (32-bit) to a seq (64-bit). 64-bit seqs are used to avoid out-of-range errors on very long games, OTOH a round is 32-bit to garantee the atomicity of its affection, even on platforms which are not native 64-bit.

Return value: the seq (64-bit integer)

Function: int64_t lw6pil_pilot_get_next_seq (lw6sys_context_t * sys_context, const lw6pil_pilot_t * pilot, int64_t timestamp)

sys_context: global system context

pilot: the object to query

timestamp: the current ticks setting (1000 ticks per second)

Returns the seq one should use to generate new events/commands at a given time (given in ticks).

Return value: none.

Function: int64_t lw6pil_pilot_get_last_commit_seq (lw6sys_context_t * sys_context, const lw6pil_pilot_t * pilot)

sys_context: global system context

pilot: the object to query

Returns the seq of the last commit (reference game_state) for this object.

Return value: the commit seq (reference object)

Function: int64_t lw6pil_pilot_get_reference_target_seq (lw6sys_context_t * sys_context, const lw6pil_pilot_t * pilot)

sys_context: global system context

pilot: the object to query

Returns the seq which is targetted in the reference game_state, this is ’how far computation will go in the reference game_state if no new commands are issued’. Note that there can always be some commands which are not yet processed, so you should not rely on this too heavily, however it gives a good idea of how things are going.

Return value: the target seq (reference object)

Function: int64_t lw6pil_pilot_get_reference_current_seq (lw6sys_context_t * sys_context, const lw6pil_pilot_t * pilot)

sys_context: global system context

pilot: the object to query

Returns the current seq in the reference game_state. There’s no lock on this call so don’t rely on this too heavily, it just gives you an idea of wether the pilot is very late on its objectives or just on time.

Return value: the current seq (reference object)

Function: int64_t lw6pil_pilot_get_max_seq (lw6sys_context_t * sys_context, const lw6pil_pilot_t * pilot)

sys_context: global system context

pilot: the object to query

Returns the max current seq in the reference or draft game states. No lock on this call so don’t rely on this too heavily, it just gives you an idea of computation state.

Return value: the current seq (reference object)

Function: int lw6pil_pilot_is_over (lw6sys_context_t * sys_context, const lw6pil_pilot_t * pilot)

sys_context: global system context

pilot: the object to query

Tells wether the game is over or not.

Return value: 1 if over, 0 if not

Function: int lw6pil_pilot_did_cursor_win (lw6sys_context_t * sys_context, const lw6pil_pilot_t * pilot, u_int16_t cursor_id)

sys_context: global system context

pilot: the object to query

cursor_id: the cursor_id concerned

Tells wether a given cursor was winner or not.

Return value: 1 if over, 0 if not

Function: int lw6pil_pilot_get_winner (lw6sys_context_t * sys_context, const lw6pil_pilot_t * pilot)

sys_context: global system context

pilot: the object to query

Gets the winner color.

Return value: a team color, -1 if no winner and/or error.

Function: int lw6pil_pilot_get_looser (lw6sys_context_t * sys_context, const lw6pil_pilot_t * pilot)

sys_context: global system context

pilot: the object to query

Gets the looser color.

Return value: a team color, -1 if no looser and/or error.

Function: lw6pil_local_cursors_t * lw6pil_pilot_get_local_cursors (lw6sys_context_t * sys_context, lw6pil_pilot_t * pilot)

sys_context: global system context

pilot: object to query

Returns a pointer on the local_cursors struct used within the object. Beware, this is the *real* pointer, not a copy...

Return value: pointer on internal object

Function: void lw6pil_pilot_checksum_log_set_interval (lw6sys_context_t * sys_context, lw6pil_pilot_t * pilot, int checksum_log_interval)

sys_context: global system context

pilot: the pilot to track

checksum_log_interval: dump interval, if 0, feature is disabled

Debugging function used to set automatically an interval at which engine will log a checksum automatically. This is typically to track down where and when there starts to be a difference between two game_states that have evolved separately. This function will propagate the parameter to all the game_states handled by the pilot, each will log its informations separately.

Return value: none

Function: char * lw6pil_seed_command_generate (lw6sys_context_t * sys_context, lw6pil_pilot_t * pilot, u_int64_t server_id, int64_t seq)

sys_context: global system context

pilot: the pilot to transform as a SEED.

server_id: ID of server issuing the command

seq: seq at which the dump should be generated

Creates the SEED command for a given pilot, that is, a command that contains macro informations about the game state such as current seq. It should be followed by a dump.

Return value: newly allocated string

Function: int64_t lw6pil_seq_random_0 (lw6sys_context_t * sys_context)

sys_context: global system context

Gets a pseudo-random start seq, why do we use this? Just to make sure even in non-network situations, seq are always very high and random, this way this is one less bug to check in networked context.

Return value: random integer value, always greater than INT_MAX

Function: int lw6pil_suite_init (lw6sys_context_t * sys_context, lw6pil_dump_t * dump, int64_t timestamp)

sys_context: global system context

dump: dump to use as a base to init the suite (out param)

timestamp: timestamp used for pilot creation (should be "now")

Build the objects used by the test suite. The idea is to wrap all this in a single function since it requires to be exactly the same every time as the test suite is very pedantic about checksums.

Return value: 1 on success, 0 on failure.

Function: int64_t lw6pil_suite_get_seq_0 (lw6sys_context_t * sys_context)

sys_context: global system context

Get the base seq_0 for the reference test suite.

Return value: 64-bit integer.

Function: u_int64_t lw6pil_suite_get_node_id (lw6sys_context_t * sys_context, int node_index)

sys_context: global system context

node_index: index of the node we want informations about

Get the node_id associated to an index, typically a 64-bit unique. The index is just a simple integer which is 0 for node A, 1 for node B, etc.

Return value: the node id, as an unsigned 64-bit integer

Function: const char * lw6pil_suite_get_command_by_node_index (lw6sys_context_t * sys_context, int node_index, int stage, int step)

sys_context: global system context

node_index: index of the node (not its id)

stage: major stage of the test suite

step: minor step of the test suite

Get the reference test suite message by node_index, stage and step.

Return value: static string, must not be freed.

Function: const char * lw6pil_suite_get_command_by_stage (lw6sys_context_t * sys_context, int stage, int step)

sys_context: global system context

stage: major stage of the test suite

step: minor step of the test suite

Get the reference test suite message by stage and step. Messages from various nodes are mixed and sorted.

Return value: static string, must not be freed.

Function: const char * lw6pil_suite_get_command_by_step (lw6sys_context_t * sys_context, int step)

sys_context: global system context

step: minor step of the test suite

Get the reference test suite message by step. Messages from various nodes and stages are mixed and sorted.

Return value: static string, must not be freed.

Function: void lw6pil_suite_get_checkpoint (lw6sys_context_t * sys_context, u_int32_t * game_state_checksum, int64_t * seq, int * round, int stage)

sys_context: global system context

game_state_checksum: expected checksum for the given checkpoint (out param)

seq: expected seq for the given checkpoint (out param)

round: expected round for the given checkpoint (out param)

stage: stage to query checksum and other info about

Gives the values which are expected for a given checkpoint. If the right messages have been feeded, then these values are expected.

Return value: none, everything in out params

Function: int lw6pil_test_register (lw6sys_context_t * sys_context, int mode)

sys_context: global system context

mode: test mode (bitmask)

Registers all tests for the libpil module.

Return value: 1 if test is successfull, 0 on error.

Function: int lw6pil_test_run (lw6sys_context_t * sys_context, int mode)

sys_context: global system context

mode: test mode (bitmask)

Runs the pil module test suite, testing most (if not all...) functions.

Return value: 1 if test is successfull, 0 on error.

Struct: lw6pil_add_args_s

Arguments passed to the ADD command.

Member of lw6pil_add_args_s: cursor_id

Type: u_int16_t

Definition: u_int16_t lw6pil_add_args_s::cursor_id

Cursor ID (16-bit non-zero unsigned int).

Member of lw6pil_add_args_s: team_color

Type: int

Definition: int lw6pil_add_args_s::team_color

Team color (0 to 9).

Struct: lw6pil_command_s

Command structure, contains both full-text version and parsed information.

Member of lw6pil_command_s: seq

Type: int64_t

Definition: int64_t lw6pil_command_s::seq

The sequence number, a very large 64-bit integer. The sequence is here because the round wouldn’t be able to stand multiple games for long as it is only 32-bit. OTOH making round a 64-bit would cause multithread problems because of non-atomicity of 64-bit affectation on truely 32-bit platforms.

Member of lw6pil_command_s: round

Type: int

Definition: int lw6pil_command_s::round

The game round.

Member of lw6pil_command_s: node_id

Type: u_int64_t

Definition: u_int64_t lw6pil_command_s::node_id

The node ID issuing that command.

Member of lw6pil_command_s: code

Type: lw6pil_command_code_t

Definition: lw6pil_command_code_t lw6pil_command_s::code

The command code.

Member of lw6pil_command_s: args

Type: lw6pil_command_args_t

Definition: lw6pil_command_args_t lw6pil_command_s::args

The command arguments, parsed.

Member of lw6pil_command_s: text

Type: char *

Definition: char* lw6pil_command_s::text

The original full text of the command.

Struct: lw6pil_dump_args_s

Arguments passed to the DUMP command.

Member of lw6pil_dump_args_s: level_hexa

Type: char *

Definition: char* lw6pil_dump_args_s::level_hexa

Hexa dump of level.

Member of lw6pil_dump_args_s: game_struct_hexa

Type: char *

Definition: char* lw6pil_dump_args_s::game_struct_hexa

Hexa dump of game struct.

Member of lw6pil_dump_args_s: game_state_hexa

Type: char *

Definition: char* lw6pil_dump_args_s::game_state_hexa

Hexa dump of game state.

Struct: lw6pil_dump_s

Stores the information contained in a dump, this is just an utility struct used to hold all the data (level, game struct, game state and pilot) together

Member of lw6pil_dump_s: level

Type: lw6map_level_t *

Definition: lw6map_level_t* lw6pil_dump_s::level

Will hold the new level if a dump is received.

Member of lw6pil_dump_s: game_struct

Type: lw6ker_game_struct_t *

Definition: lw6ker_game_struct_t* lw6pil_dump_s::game_struct

Will hold the new game struct if a dump is received.

Member of lw6pil_dump_s: game_state

Type: lw6ker_game_state_t *

Definition: lw6ker_game_state_t* lw6pil_dump_s::game_state

Will hold the new game state if a dump is received.

Member of lw6pil_dump_s: pilot

Type: lw6pil_pilot_p

Definition: lw6pil_pilot_p lw6pil_dump_s::pilot

Will hold the new pilot if a dump is received.

Struct: lw6pil_local_cursors_s

Contains information about all local cursors, which will override information from game state.

Member of lw6pil_local_cursors_s: main_cursor_id

Type: u_int16_t

Definition: u_int16_t lw6pil_local_cursors_s::main_cursor_id

Main cursor ID (16-bit non-zero unsigned int). By main, we usually mean the mouse-driven one but necessarily. But still, this is a cursor which will have a special role, it will be used to center the map if needed, among other things.

Member of lw6pil_local_cursors_s: main_i

Type: int

Definition: int lw6pil_local_cursors_s::main_i

Main cursor index.

Member of lw6pil_local_cursors_s: nb_cursors

Type: int

Definition: int lw6pil_local_cursors_s::nb_cursors

Number of cursors.

Member of lw6pil_local_cursors_s: cursors

Type: lw6pil_local_cursor_t

Definition: lw6pil_local_cursor_t lw6pil_local_cursors_s::cursors[LW6MAP_MAX_NB_CURSORS]

The cursors array.

Struct: lw6pil_local_cursor_s

Stores informations about local cursors. This is usefull for user feedback. Indeed there can be some delay between, for instance, a mouse move or a keyboard press, and the time this information makes it through the whole pipeline. Players wouldn’t understand such a lag so for local cursors we override the information from the game state with that information we get right from the GUI.

Member of lw6pil_local_cursor_s: cursor_id

Type: u_int16_t

Definition: u_int16_t lw6pil_local_cursor_s::cursor_id

Cursor ID (16-bit non-zero unsigned int).

Member of lw6pil_local_cursor_s: x

Type: int

Definition: int lw6pil_local_cursor_s::x

X position (map coords).

Member of lw6pil_local_cursor_s: y

Type: int

Definition: int lw6pil_local_cursor_s::y

Y position (map coords).

Member of lw6pil_local_cursor_s: mouse_controlled

Type: int

Definition: int lw6pil_local_cursor_s::mouse_controlled

Wether this cursor is mouse controlled. If yes, then information will be taken directly from the mouse driver.

Member of lw6pil_local_cursor_s: is_main

Type: int

Definition: int lw6pil_local_cursor_s::is_main

Wether this cursor is the main cursor.

Struct: lw6pil_pilot_s

Pilot is a container for several game states, a reference state which we can rely upon and a draft state which is anticipated to provide interactive feedback but reflects non-validated informations. The first member, id, is the same as the internal _lw6pil_pilot_t structure. The rest of it is hidden. The program will cast from lw6pil_pilot_t to _lw6pil_pilot_t internally.

Member of lw6pil_pilot_s: id

Type: u_int32_t

Definition: u_int32_t lw6pil_pilot_s::id

The id of the object, this is non-zero and unique within one run session, incremented at each object creation.

Struct: lw6pil_remove_args_s

Arguments passed to the REMOVE command.

Member of lw6pil_remove_args_s: cursor_id

Type: u_int16_t

Definition: u_int16_t lw6pil_remove_args_s::cursor_id

Cursor ID (16-bit non-zero unsigned int).

Struct: lw6pil_set_args_s

Arguments passed to the SET command.

Member of lw6pil_set_args_s: cursor_id

Type: u_int64_t

Definition: u_int64_t lw6pil_set_args_s::cursor_id

Cursor ID (16-bit non-zero unsigned int).

Member of lw6pil_set_args_s: x

Type: int

Definition: int lw6pil_set_args_s::x

X position (map coords).

Member of lw6pil_set_args_s: y

Type: int

Definition: int lw6pil_set_args_s::y

Y position (map coords).

Member of lw6pil_set_args_s: fire

Type: int

Definition: int lw6pil_set_args_s::fire

Wether to activate primary weapon.

Member of lw6pil_set_args_s: fire2

Type: int

Definition: int lw6pil_set_args_s::fire2

Wether to activate secondary weapon.

Struct: lw6pil_worker_s

Worker thread data, used to calculate stuff in a separate thread. The principle is simple, it tries to keep up with a given target round, whenever this round isn’t reached, it computes more and more rounds.

Member of lw6pil_worker_s: run

Type: int

Definition: volatile int lw6pil_worker_s::run

Wether this thread should run, 0 will stop it.

Member of lw6pil_worker_s: verified

Type: int

Definition: int lw6pil_worker_s::verified

Wether this is running in verified mode or not.

Member of lw6pil_worker_s: current_round

Type: int

Definition: volatile int lw6pil_worker_s::current_round

Current game round.

Member of lw6pil_worker_s: target_round

Type: int

Definition: volatile int lw6pil_worker_s::target_round

Round up to which we should compute stuff.

Member of lw6pil_worker_s: computed_rounds

Type: int

Definition: volatile int lw6pil_worker_s::computed_rounds

How many rounds where computed since object creation.

Member of lw6pil_worker_s: over

Type: int

Definition: volatile int lw6pil_worker_s::over

Wether the game is over or not.

Member of lw6pil_worker_s: compute_thread

Type: lw6sys_thread_handler_t *

Definition: lw6sys_thread_handler_t* lw6pil_worker_s::compute_thread

The thread that does the job.

Member of lw6pil_worker_s: global_mutex

Type: lw6sys_mutex_t *

Definition: lw6sys_mutex_t* lw6pil_worker_s::global_mutex

Global data mutex.

Member of lw6pil_worker_s: compute_mutex

Type: lw6sys_mutex_t *

Definition: lw6sys_mutex_t* lw6pil_worker_s::compute_mutex

Mutex used for the computing thread.

Member of lw6pil_worker_s: game_state

Type: lw6ker_game_state_t *

Definition: lw6ker_game_state_t* lw6pil_worker_s::game_state

Game state the computing thread is working on.

Member of lw6pil_worker_s: commands

Type: lw6sys_list_r_t *

Definition: lw6sys_list_r_t* lw6pil_worker_s::commands

List of commands to be processed.

Member of lw6pil_worker_s: dump

Type: lw6pil_dump_t

Definition: lw6pil_dump_t lw6pil_worker_s::dump

Dump information.

Struct: lw6pil_command_args_u

Arguments passed to various commands.

Member of lw6pil_command_args_u: add

Type: lw6pil_add_args_t

Definition: lw6pil_add_args_t lw6pil_command_args_u::add

Arguments when command is ADD.

Member of lw6pil_command_args_u: remove

Type: lw6pil_remove_args_t

Definition: lw6pil_remove_args_t lw6pil_command_args_u::remove

Arguments when command is REMOVE.

Member of lw6pil_command_args_u: set

Type: lw6pil_set_args_t

Definition: lw6pil_set_args_t lw6pil_command_args_u::set

Arguments when command is SET.

Member of lw6pil_command_args_u: dump

Type: lw6pil_dump_args_t

Definition: lw6pil_dump_args_t lw6pil_command_args_u::dump

Arguments when command is DUMP.


Next: , Previous: , Up: C API   [Contents][Index]