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


5.29 libker

5.29.1 Overview

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

5.29.2 API

Function: char * lw6ker_capture_str (lw6sys_context_t * sys_context, const lw6ker_game_state_t * game_state)

sys_context: global system context

game_state: game state to represent

Gives a string representation, an ASCII capture of the game. This representation is suitable for debugging, typically print it to a VT100 console.

Return value: dynamically allocated string.

Function: void lw6ker_game_state_checksum_log_set_interval (lw6sys_context_t * sys_context, lw6ker_game_state_t * game_state, int checksum_log_interval)

sys_context: global system context

game_state: the game_state 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.

Return value: none

Function: void lw6ker_cursor_reset (lw6sys_context_t * sys_context, lw6ker_cursor_t * cursor)

sys_context: global system context

cursor: the cursor to reset

Sets a cursor to defaults (disabled). This function will not touch the node_id and cursor_id fields, so you can call it on an already used cursor, it will stay usable.

Return value: none

Function: lw6ker_game_state_t * lw6ker_game_state_new (lw6sys_context_t * sys_context, const lw6ker_game_struct_t * game_struct, lw6sys_progress_t * progress)

sys_context: global system context

game_struct: game_struct use to construct the object

progress: progress indicator

Creates a game state from a game struct. The game struct must be kept (never freed) while game_state is in use.

Return value: newly created object.

Function: void lw6ker_game_state_free (lw6sys_context_t * sys_context, lw6ker_game_state_t * game_state)

sys_context: global system context

game_state: the object to free

Frees a game_state object, releases all required objects. At this stage the map_struct must still be available.

Return value: none

Function: void lw6ker_game_state_point_to (lw6sys_context_t * sys_context, lw6ker_game_state_t * game_state, const lw6ker_game_struct_t * game_struct)

sys_context: global system context

game_state: the game_state to modify

game_struct: the game_struct to point to

This can be used when one makes a copy (dup) of a game struct and for some reason want the game_state to point on this new copy. Of course you should make the game_state point to a game_struct that is identical to the one that was used to construct the object in the first place. Use at your own risk.

Return value: none

Function: int lw6ker_game_state_memory_footprint (lw6sys_context_t * sys_context, lw6ker_game_state_t * game_state)

sys_context: global system context

game_state: the game_state to query

Returns the approximative amount of memory taken by the object.

Return value: number of bytes (approximation)

Function: char * lw6ker_game_state_repr (lw6sys_context_t * sys_context, const lw6ker_game_state_t * game_state)

sys_context: global system context

game_state: the game_state to query

Gives a readable representation of the object.

Return value: newly allocated string, must be freed

Function: int lw6ker_game_state_can_sync (lw6sys_context_t * sys_context, lw6ker_game_state_t * dst, const lw6ker_game_state_t * src)

sys_context: global system context

dst: the destination game_state

src: the source game_state

Tells wether src and dst can be synced. This is not a fool proof function but in most cases it will raise the error, use it to avoid blunders. It just compares dst and src and tries to guess if they correspond to the same logical objects.

Return value: 1 if they are syncable, 0 if not.

Function: int lw6ker_game_state_sync (lw6sys_context_t * sys_context, lw6ker_game_state_t * dst, const lw6ker_game_state_t * src)

sys_context: global system context

dst: the destination game_state

src: the source game_state

Fundamental function, used to carbon copy a game state to another, this is intensively used to keep too tracks of the game state, one most-up-to-date but probably wrong, the one we use to display on the screen, and one slightly outdated (or very outdated if network is slow) but that we’re sure of, something 100% bullet proof we can rely on.

Return value: 1 on success, 0 on error

Function: lw6ker_game_state_t * lw6ker_game_state_dup (lw6sys_context_t * sys_context, const lw6ker_game_state_t * game_state, lw6sys_progress_t * progress)

sys_context: global system context

game_state: the game_state to copy

progress: progress indicator

Dups (copy) a game_state object. The newly created object points to the same game_struct but is an independant copy, you can play a whole different game on it. In practice this is often used to create the game_state objects for anticipation in network games.

Return value: newly created object

Function: u_int32_t lw6ker_game_state_checksum (lw6sys_context_t * sys_context, const lw6ker_game_state_t * game_state)

sys_context: global system context

game_state: the game_state to query

Calculates the checksum of a game_state, this can be very usefull to make sure two states are identicall (prevent network errors and/or cheating).

Return value: 32-bit checksum

Function: void lw6ker_game_state_get_shape (lw6sys_context_t * sys_context, const lw6ker_game_state_t * game_state, lw6sys_whd_t * shape)

sys_context: global system context

game_state: the game_state to query

shape: the shape (out param)

Retrieves the shape (w*h*d)of the game_state.

Return value: none.

Function: int lw6ker_game_state_get_w (lw6sys_context_t * sys_context, const lw6ker_game_state_t * game_state)

sys_context: global system context

game_state: the game_state to query

Retrieves the width (shape.w) of the game_state.

Return value: the width.

Function: int lw6ker_game_state_get_h (lw6sys_context_t * sys_context, const lw6ker_game_state_t * game_state)

sys_context: global system context

game_state: the game_state to query

Retrieves the height (shape.h) of the game_state.

Return value: the height.

Function: int lw6ker_game_state_get_d (lw6sys_context_t * sys_context, const lw6ker_game_state_t * game_state)

sys_context: global system context

game_state: the game_state to query

Retrieves the depth (shape.d, AKA number of layers) of the game_state.

Return value: the depth.

Function: int lw6ker_game_state_register_node (lw6sys_context_t * sys_context, lw6ker_game_state_t * game_state, u_int64_t node_id)

sys_context: global system context

game_state: the game_state to act on

node_id: the id of the node to register

Registers a node in the game, this must be done, else no action will be allowed (such as adding a cursor or moving it). There’s a limited number of nodes allowed, and ids must be unique.

Return value: 1 on success, 0 on failure.

Function: int lw6ker_game_state_unregister_node (lw6sys_context_t * sys_context, lw6ker_game_state_t * game_state, u_int64_t node_id)

sys_context: global system context

game_state: the game_state to act on

node_id: the id of the node to register

Unregisters a node in the game, this must be done when a node leaves the game, it will free ressources and allow others to connect.

Return value: 1 on success, 0 on failure.

Function: int lw6ker_game_state_node_exists (lw6sys_context_t * sys_context, lw6ker_game_state_t * game_state, u_int64_t node_id)

sys_context: global system context

game_state: the game_state to query

node_id: the node to test

Tells wether a node is present in a game.

Return value: 1 if node is in game, 0 if not

Function: int lw6ker_game_state_get_node_info (lw6sys_context_t * sys_context, lw6ker_game_state_t * game_state, u_int16_t node_id, u_int32_t * last_command_round)

sys_context: global system context

game_state: game_state to query

node_id: the node to get info about

last_command_round: the last round for which a command was issued (out parameter)

Queries information about a given node, mostly, what was the last round we got a command.

Return value: 1 on success, 0 on error.

Function: int lw6ker_game_state_add_cursor (lw6sys_context_t * sys_context, lw6ker_game_state_t * game_state, u_int64_t node_id, u_int16_t cursor_id, int team_color)

sys_context: global system context

game_state: the game_state to act upon

node_id: the node issuing the command

cursor_id: the id of the cursor to add

team_color: the color we wish

Adds a cursor in a game. Note that if there’s already a cursor with that id, it will fail, and the color is only the color we wish, we might indeed be attributed another color on a successfull call.

Return value: 1 on success, 0 on error.

Function: int lw6ker_game_state_remove_cursor (lw6sys_context_t * sys_context, lw6ker_game_state_t * game_state, u_int64_t node_id, u_int16_t cursor_id)

sys_context: global system context

game_state: the game_state to act upon

node_id: the node issuing the command

cursor_id: the id of the cursor to remove

Removes a cursor from the game, corresponding teams will be removed if needed.

Return value: 1 on success, 0 on failure.

Function: int lw6ker_game_state_cursor_exists (lw6sys_context_t * sys_context, const lw6ker_game_state_t * game_state, u_int16_t cursor_id)

sys_context: global system context

game_state: the game_state to query

cursor_id: the cursor to test

Tells wether a cursor is present in the game.

Return value: 1 if cursor exists, 0 if not.

Function: int lw6ker_game_state_get_cursor (lw6sys_context_t * sys_context, const lw6ker_game_state_t * game_state, lw6ker_cursor_t * cursor, u_int16_t cursor_id)

sys_context: global system context

game_state: the game_state to query

cursor: the cursor data (out param)

cursor_id: the cursor to query

Get a pointer on a given cursor, pointer is read-only.

Return value: 1 on success, 0 on failure.

Function: void lw6ker_game_state_get_cursor_by_index (lw6sys_context_t * sys_context, const lw6ker_game_state_t * game_state, lw6ker_cursor_t * cursor, int i)

sys_context: global system context

game_state: the game state to query

cursor: the cursor (out param)

i: the index

Gets the cursor information, using its index. This is usefull to walk the whole cursor without knowing their ids. Pointer is read-only.

Return value: none.

Function: int lw6ker_game_state_set_cursor (lw6sys_context_t * sys_context, lw6ker_game_state_t * game_state, lw6ker_cursor_t * cursor)

sys_context: global system context

game_state: the game_state to act upon

cursor: the cursor

Sets a cursor, that is, changes its position, this is pretty much anything we can do about a cursor except adding or removing it, just because of Liquid War very simple rules. The passed pointer may be freed after the call, only the cursor_id, node_id, x, y and fire fields are used, others are ignored. More precisely, the enabled will be ignored, it’s not a valid way to add/remove teams.

Return value: 1 on success, 0 on failure

Function: int lw6ker_game_state_team_exists (lw6sys_context_t * sys_context, const lw6ker_game_state_t * game_state, int team_color)

sys_context: global system context

game_state: the game_state to query

team_color: the team color to test

Tells wether a team color is present in the game. Note that this is different from cursor ids.

Return value: 1 if team exists, 0 if not.

Function: int lw6ker_game_state_get_team_info (lw6sys_context_t * sys_context, const lw6ker_game_state_t * game_state, int team_color, int32_t * nb_cursors, int32_t * nb_fighters)

sys_context: global system context

game_state: the game_state to query

team_color: the color to get informations about

nb_cursors: number of cursors with this color (out param)

nb_fighters: number of fighters with this color (out param)

Gets informations about a given color. Indeed, a color can have several cursors, and knowing how many fighters there are with a given color is probably the most important things about a color.

Return value: 1 on success, 0 on failure.

Function: int lw6ker_game_state_get_nb_teams (lw6sys_context_t * sys_context, const lw6ker_game_state_t * game_state)

sys_context: global system context

game_state: the game_state to query

Tells how many teams there are in a game. This is different from the cursors number, there can be more cursors than teams, because a team can have several cursors.

Return value: the number of teams.

Function: void lw6ker_game_state_do_spread (lw6sys_context_t * sys_context, lw6ker_game_state_t * game_state, u_int32_t team_mask)

sys_context: global system context

game_state: the game_state to act upon

team_mask: a binary mask of which gradients (teams) must be spreaded

Spreads the gradient, that is, calculates the potential of each point on the map, ie the distance to the closest cursor. The binary mask allows gradient to be spread for only some teams, this is usefull in a multithreaded context, as gradients can be calculated separately.

Return value: none

Function: void lw6ker_game_state_do_move (lw6sys_context_t * sys_context, lw6ker_game_state_t * game_state, u_int32_t team_mask)

sys_context: global system context

game_state: the game_state to act upon

team_mask: a binary mask of which teams must be moved

Moves the fighters, note that you must calculate the gradient from time to time else they go to the wrong places. The team_mask allows the moving of only some given teams, but moving (for instance) even teams then odd teams isn’t the same as moving odd teams then even teams. Whereas as far as gradient calculation is concerned, this could have been true, you could have multithreaded that.

Return value: none.

Function: void lw6ker_game_state_finish_round (lw6sys_context_t * sys_context, lw6ker_game_state_t * game_state)

sys_context: global system context

game_state: the game_state to act upon

Finishes a round, that is, vaccums various stuff, checks if some team has lost, and so on. This is complementary to the spread and move steps, it should be called at each round.

Return value: none.

Function: void lw6ker_game_state_do_round (lw6sys_context_t * sys_context, lw6ker_game_state_t * game_state)

sys_context: global system context

game_state: the game_state to act upon

This is a fundamental function, it’s called at each round, it fires all the complex calculations in the game, the real core algorithm. Every time this function is called, the round is "over" and the game state is ready for the next... round. It’s equivalent to calling the spread, move and finish functions.

Return value: none.

Function: u_int32_t lw6ker_game_state_get_moves (lw6sys_context_t * sys_context, const lw6ker_game_state_t * game_state)

sys_context: global system context

game_state: the game_state to query

Returns the number of moves done on this game.

Return value: number of moves.

Function: u_int32_t lw6ker_game_state_get_spreads (lw6sys_context_t * sys_context, const lw6ker_game_state_t * game_state)

sys_context: global system context

game_state: the game_state to query

Returns the number of spreads done on this game.

Return value: number of spreads.

Function: u_int32_t lw6ker_game_state_get_rounds (lw6sys_context_t * sys_context, const lw6ker_game_state_t * game_state)

sys_context: global system context

game_state: the game_state to query

Returns the number of rounds done on this game.

Return value: number of rounds.

Function: u_int32_t lw6ker_game_state_get_total_rounds (lw6sys_context_t * sys_context, const lw6ker_game_state_t * game_state)

sys_context: global system context

game_state: the game_state to query

Returns the number of playable rounds in the game, that is the number of rounds to be played if game goes up to the time limit. This is a fixed number, if game slows down then time is stretched, but the the exact maximum number of rounds is known at game start, and it is the number returned by this function.

Return value: number of rounds in the game

Function: int lw6ker_game_state_is_over (lw6sys_context_t * sys_context, const lw6ker_game_state_t * game_state)

sys_context: global system context

game_state: the game_state to query

Tells wether the game is over or not. The answer depends on time limit, game rules, and of course what happened on the battlefield.

Return value: 1 if over, 0 if not.

Function: int lw6ker_game_state_did_cursor_win (lw6sys_context_t * sys_context, const lw6ker_game_state_t * game_state, u_int16_t cursor_id)

sys_context: global system context

game_state: game_state to query

cursor_id: the cursor to test

Tells wether a cursor was the winner after a game is over.

Return value: 1 if cursor is in winning team, 0 if not.

Function: int lw6ker_game_state_get_winner (lw6sys_context_t * sys_context, const lw6ker_game_state_t * game_state, int excluded_team)

sys_context: global system context

game_state: the game_state to query

excluded_team: a team to exclude

Returns the winner, if you set excluded_team to something else than a valid team number (for instance -1, but 0 is a valid team) then this team will be excluded from search. This is usefull if you want to find out who’s the best positionned player while excluding yourself, for instance if you’re a bot.

Return value: the winner team number, note that it can be invalid (-1) if there’s no winner (for example, there are no teams on the map).

Function: int lw6ker_game_state_get_looser (lw6sys_context_t * sys_context, const lw6ker_game_state_t * game_state, int excluded_team)

sys_context: global system context

game_state: the game_state to query

excluded_team: a team to exclude

Returns the looser, if you set excluded_team to something else than a valid team number (for instance -1, but 0 is a valid team) then this team will be excluded from search. This is usefull if you want to find out who’s the worst positionned player while excluding yourself, for instance if you’re a bot.

Return value: the looser team number, note that it can be invalid (-1) if there’s no looser (for example, there are no teams on the map).

Function: int32_t lw6ker_game_state_get_nb_active_fighters (lw6sys_context_t * sys_context, const lw6ker_game_state_t * game_state)

sys_context: global system context

game_state: the game_state to query

Gets the number of active fighters, this is relatively constant within the game, it does not change when someone looses, but it can vary when a new team arrives or disappears.

Return value: number of fighters.

Function: int32_t lw6ker_game_state_get_time_elapsed (lw6sys_context_t * sys_context, const lw6ker_game_state_t * game_state)

sys_context: global system context

game_state: the game_state to query

Returns the time elapsed, this is not the real time you’d time with an atomic clock, rather the time that would have elapsed if game had been run at its nominal speed. There can be a difference if your computer is too slow, among other things.

Return value: time elapsed, in seconds.

Function: int32_t lw6ker_game_state_get_time_left (lw6sys_context_t * sys_context, const lw6ker_game_state_t * game_state)

sys_context: global system context

game_state: the game_state to query

Returns the time left, this is not the real time you’d time with an atomic clock, rather the time that would theorically be left is game was to be run at its nominal speed. There can be a difference if your computer is too slow, among other things. You shouldn’t rely on this to know wether a game is over or not, there’s another dedicated function for that.

Return value: time left, in seconds.

Function: int32_t lw6ker_game_state_get_global_history (lw6sys_context_t * sys_context, const lw6ker_game_state_t * game_state, int i, int team_id)

sys_context: global system context

game_state: the game_state to query

i: the index of the history point

team_id: the team to query

Returns the number of fighters at some point in the past (the lower i, the oldest). The history scrolls automatically and erases itself at some point, it’s of constant length. This is the global, long term history, reflects the whole game and could be used for an end-game score screen.

Return value: number of fighters at that time.

Function: int32_t lw6ker_game_state_get_latest_history (lw6sys_context_t * sys_context, const lw6ker_game_state_t * game_state, int i, int team_id)

sys_context: global system context

game_state: the game_state to query

i: the index of the history point

team_id: the team to query

Returns the number of fighters at some point in the past (the lower i, the oldest). The history scrolls automatically and erases itself at some point, it’s of constant length. This is the latest, short term history, reflects the recent game evolutions and could be used to display an in-game monitor.

Return value: number of fighters at that time.

Function: int32_t lw6ker_game_state_get_global_history_max (lw6sys_context_t * sys_context, const lw6ker_game_state_t * game_state)

sys_context: global system context

game_state: game_state to query

Returns the maximum value, that is, the maximum number of fighters, all teams combined, for this history. This can be used to scale charts. This function for the global long term history.

Return value: max number of fighters.

Function: int32_t lw6ker_game_state_get_latest_history_max (lw6sys_context_t * sys_context, const lw6ker_game_state_t * game_state)

sys_context: global system context

game_state: game_state to query

Returns the maximum value, that is, the maximum number of fighters, all teams combined, for this history. This can be used to scale charts. This function for the latest short term history.

Return value: max number of fighters.

Function: int32_t lw6ker_game_state_get_fighter_id (lw6sys_context_t * sys_context, const lw6ker_game_state_t * game_state, int32_t x, int32_t y, int32_t z)

sys_context: global system context

game_state: game_state to query

x: x position

y: y position

z: z position

Gets the id of a fighter in a given position. Previous versions of the game used to have this declared inline static for speed, but the price to pay in terms of maintainability was too high: too much stuff from the ker module had to be kept public. This functions is very likely to be called often when one wants to know what’s happening on the battlefield, to draw it, for instance. If there’s no fighter, the id is negative, any id equal or greater than 0 (returned by this function) is valid.

Return value: the id of the fighter at that position.

Function: lw6ker_fighter_t * lw6ker_game_state_get_fighter_rw_by_id (lw6sys_context_t * sys_context, lw6ker_game_state_t * game_state, int32_t fighter_id)

sys_context: global system context

game_state: game_state to query

fighter_id: the id of the fighter

Gets a fighter by its id. Internally, all fighters are stored in an array so it could be "safe" to get fighter with id 0 then walk the array. Previous versions of the game used to have this public (the array), it has been hidden since. Pointer is read/write. Pointer is read/write.

Return value: pointer to the fighter with the given id.

Function: lw6ker_fighter_t * lw6ker_game_state_get_fighter_rw_safe (lw6sys_context_t * sys_context, lw6ker_game_state_t * game_state, int32_t x, int32_t y, int32_t z)

sys_context: global system context

game_state: game_state to query

x: x position

y: y position

z: z position

Gets a fighter by its position. This function will check for boundaries, if there’s no fighter in this place, it will return NULL, but nothing worse can happen. More precisely, if the place is in a wall, it won’t bug, unlike the non-bullet-proof equivalent of this function. Pointer is read/write.

Return value: pointer to the fighter at this position, or NULL if none.

Function: lw6ker_fighter_t * lw6ker_game_state_get_fighter_rw_unsafe (lw6sys_context_t * sys_context, lw6ker_game_state_t * game_state, int32_t x, int32_t y, int32_t z)

sys_context: global system context

game_state: game_state to query

x: x position

y: y position

z: z position

Gets a fighter by its position. This function will not check for boundaries, if there’s no fighter in this place, not only will it probably not return a valid value, but it will also even segfault before that, trying to access non-existing structures in menory. So only call this if you’re sure there’s a fighter here. Pointer is read/write.

Return value: pointer to the fighter at this position, or NULL if none.

Function: const lw6ker_fighter_t * lw6ker_game_state_get_fighter_ro_by_id (lw6sys_context_t * sys_context, const lw6ker_game_state_t * game_state, int32_t fighter_id)

sys_context: global system context

game_state: game_state to query

fighter_id: the id of the fighter

Gets a fighter by its id. Internally, all fighters are stored in an array so it could be "safe" to get fighter with id 0 then walk the array. Previous versions of the game used to have this public (the array), it has been hidden since. Pointer is read-only. Pointer is read-only.

Return value: pointer to the fighter with the given id.

Function: const lw6ker_fighter_t * lw6ker_game_state_get_fighter_ro_safe (lw6sys_context_t * sys_context, const lw6ker_game_state_t * game_state, int32_t x, int32_t y, int32_t z)

sys_context: global system context

game_state: game_state to query

x: x position

y: y position

z: z position

Gets a fighter by its position. This function will check for boundaries, if there’s no fighter in this place, it will return NULL, but nothing worse can happen. More precisely, if the place is in a wall, it won’t bug, unlike the non-bullet-proof equivalent of this function. Pointer is read-only.

Return value: pointer to the fighter at this position, or NULL if none.

Function: const lw6ker_fighter_t * lw6ker_game_state_get_fighter_ro_unsafe (lw6sys_context_t * sys_context, const lw6ker_game_state_t * game_state, int32_t x, int32_t y, int32_t z)

sys_context: global system context

game_state: game_state to query

x: x position

y: y position

z: z position

Gets a fighter by its position. This function will not check for boundaries, if there’s no fighter in this place, not only will it probably not return a valid value, but it will also even segfault before that, trying to access non-existing structures in menory. So only call this if you’re sure there’s a fighter here. Pointer is read-only.

Return value: pointer to the fighter at this position, or NULL if none.

Function: int lw6ker_game_state_get_zone_potential (lw6sys_context_t * sys_context, const lw6ker_game_state_t * game_state, int i, int team_id)

sys_context: global system context

game_state: the game_state to query

team_id: the team id (color)

Gets the potential of a zone. In practice this is not needed to make the game function, you need not call this to know how to move fighters, however the information can be interesting for debugging.

Return value: the potential

Function: int lw6ker_game_state_get_charge_per1000 (lw6sys_context_t * sys_context, const lw6ker_game_state_t * game_state, int team_color)

sys_context: global system context

game_state: game_state to query

team_color: the team color to query

Returns the charge ratio for a given team/color. A value of 100 means fire is enabled, more than 1000 means super-charge, under 100 means you have to wait.

Return value: integer value.

Function: int lw6ker_game_state_get_weapon_per1000_left (lw6sys_context_t * sys_context, const lw6ker_game_state_t * game_state, int team_color)

sys_context: global system context

game_state: game_state to query

team_color: the team color to query

Returns how much of the weapon is yet to be consumed for a given team. More than 1000 means extra time, 1000 is standard time to be elapsed, 0 means it’s over.

Return value: integer value.

Function: int lw6ker_game_state_get_latest_weapon (lw6sys_context_t * sys_context, const lw6ker_game_state_t * game_state, int * team_color, int * weapon_id, int * per1000_left)

sys_context: global system context

game_state: game_state to query

team_color: the team color corresponding to last weapon (out param)

weapon_id: the corresponding weapon_id (out param)

per1000_left: how much of the weapon is yet to be spent (out param)

Returns informations about the latest weapon, this is typically for drawing purposes, just query this and you know if you need to paint everything in red, green, whatever, as far as the default backend is concerned. In case there’s no weapon, well, parameters are untouched. Pointers can be passed as NULL.

Return value: 1 if found, 0 if not.

Function: int lw6ker_game_state_get_nb_colors (lw6sys_context_t * sys_context, const lw6ker_game_state_t * game_state)

sys_context: global system context

game_state: game state to query

Gives the max number of colors (AKA teams) that are present in the game. This is just a simple utility/wrapper function which is meant to be exported to Guile scripts.

Return value: number of colors

Function: int lw6ker_game_state_get_nb_cursors (lw6sys_context_t * sys_context, const lw6ker_game_state_t * game_state)

sys_context: global system context

game_state: game state to query

Gives the max number of cursors that are present in the game. This is just a simple utility/wrapper function which is meant to be exported to Guile scripts.

Return value: number of cursors

Function: int lw6ker_game_state_get_nb_nodes (lw6sys_context_t * sys_context, const lw6ker_game_state_t * game_state)

sys_context: global system context

game_state: game state to query

Gives the max number of nodes that are present in the game. This is just a simple utility/wrapper function which is meant to be exported to Guile scripts.

Return value: number of nodes

Function: lw6ker_game_struct_t * lw6ker_game_struct_new (lw6sys_context_t * sys_context, const lw6map_level_t * level, lw6sys_progress_t * progress)

sys_context: global system context

level: the level on which the game_struct is based

progress: progress indicator

Creates a new game_struct from a level. The game_struct is different from the level in the sense that the game_struct does contain algorithmic specific optimizations, it’s a ready-to-use struct desgined for execution speed, while the plain level just stores information.

Return value: newly allocated object

Function: void lw6ker_game_struct_free (lw6sys_context_t * sys_context, lw6ker_game_struct_t * game_struct)

sys_context: global system context

game_struct: the game_struct to free

Frees a game_struct object, releasing all required stuff. The source level must still be available when freeing this.

Return value: none

Function: void lw6ker_game_struct_point_to (lw6sys_context_t * sys_context, lw6ker_game_struct_t * game_struct, const lw6map_level_t * level)

sys_context: global system context

game_struct: the game_struct to modify

level: the level to point to

This can be used when one makes a copy (dup) of a level and for some reason want the game_struct to point on this new copy. Of course you should make the game_struct point to a level that is identical to the one that was used to construct the object in the first place. Use at your own risk.

Return value: none

Function: int lw6ker_game_struct_memory_footprint (lw6sys_context_t * sys_context, const lw6ker_game_struct_t * game_struct)

sys_context: global system context

game_struct: the game_struct to query

Returns the approximative amount of memory taken by the object.

Return value: number of bytes (approximation)

Function: char * lw6ker_game_struct_repr (lw6sys_context_t * sys_context, const lw6ker_game_struct_t * game_struct)

sys_context: global system context

game_struct: the game_struct to query

Gives a readable representation of the object.

Return value: newly allocated string, must be freed

Function: lw6ker_game_struct_t * lw6ker_game_struct_dup (lw6sys_context_t * sys_context, const lw6ker_game_struct_t * game_struct, lw6sys_progress_t * progress)

sys_context: global system context

game_struct: the game_struct to copy

progress: progress indicator

Dups (copy) a game_struct object. The newly created object points to the same game_struct but is an independant copy, you can play a whole different game on it. In practice this is often used to create the game_struct objects for anticipation in network games.

Return value: newly created object

Function: u_int32_t lw6ker_game_struct_checksum (lw6sys_context_t * sys_context, const lw6ker_game_struct_t * game_struct)

sys_context: global system context

game_struct: the game_struct to query

Calculates the checksum of a game_struct, this can be very usefull to make sure two structs are identicall (prevent network errors and/or cheating).

Return value: 32-bit checksum

Function: void lw6ker_game_struct_get_shape (lw6sys_context_t * sys_context, const lw6ker_game_struct_t * game_struct, lw6sys_whd_t * shape)

sys_context: global system context

game_struct: the game_struct to query

shape: the shape (out param)

Retrieves the shape (w*h*d)of the game_struct.

Return value: none.

Function: int lw6ker_game_struct_get_w (lw6sys_context_t * sys_context, const lw6ker_game_struct_t * game_struct)

sys_context: global system context

game_struct: the game_struct to query

Retrieves the width (shape.w) of the game_struct.

Return value: the width.

Function: int lw6ker_game_struct_get_h (lw6sys_context_t * sys_context, const lw6ker_game_struct_t * game_struct)

sys_context: global system context

game_struct: the game_struct to query

Retrieves the height (shape.h) of the game_struct.

Return value: the height.

Function: int lw6ker_game_struct_get_d (lw6sys_context_t * sys_context, const lw6ker_game_struct_t * game_struct)

sys_context: global system context

game_struct: the game_struct to query

Retrieves the depth (shape.d, AKA number of layers) of the game_struct.

Return value: the depth.

Function: int lw6ker_game_struct_is_fg (lw6sys_context_t * sys_context, const lw6ker_game_struct_t * game_struct, int32_t x, int32_t y, int32_t z)

sys_context: global system context

game_struct: the game_struct to query

x: x position

y: y position

z: z position

Tests wether a given position is foreground, that is, occupied by a wall.

Return value: 1 if foreground (wall, fighters can’t move), 0 if not

Function: int lw6ker_game_struct_is_bg (lw6sys_context_t * sys_context, const lw6ker_game_struct_t * game_struct, int32_t x, int32_t y, int32_t z)

sys_context: global system context

game_struct: the game_struct to query

x: x position

y: y position

z: z position

Tests wether a given position is background, that is, there’s no wall.

Return value: 1 if background (wall, fighters can move), 0 if not

Function: void lw6ker_game_struct_get_zones_info (lw6sys_context_t * sys_context, const lw6ker_game_struct_t * game_struct, int * nb_zones, int * max_zone_size)

sys_context: global system context

game_struct: game_struct to query

nb_zones: the maximum zone size (out param, can be NULL)

max_zone_size: the maximum zone size (out param, can be NULL)

This function gets information about the internal zoning system, can be used for debugging.

Return value: none.

Function: void lw6ker_game_struct_get_zone_info (lw6sys_context_t * sys_context, const lw6ker_game_struct_t * game_struct, int i, lw6sys_xyz_t * zone_pos, int * zone_size)

sys_context: global system context

game_struct: game_struct to query

i: index of the zone to query

zone_pos: coord of the zone, top-left corner (out param, can be NULL)

zone_size: size of the zone (out param, can be NULL)

This function gets information about the internal zoning system, can be used for debugging.

Return value: none

Function: int32_t lw6ker_game_struct_get_zone_id (lw6sys_context_t * sys_context, const lw6ker_game_struct_t * game_struct, int32_t x, int32_t y, int32_t z)

sys_context: global system context

game_struct: the game_struct to query

x: x pos

y: y pos

z: z pos

Gets the zone id for a given position. The id returned can then be used to query for a potential, for instance.

Return value: the zone id

Function: void lw6ker_game_struct_find_free_slot_near (lw6sys_context_t * sys_context, const lw6ker_game_struct_t * game_struct, lw6sys_xyz_t * there, lw6sys_xyz_t here)

sys_context: global system context

game_struct: the game_struct to query

there: the closest free slot (out param)

here: where we’d like to be

Tries to find the closest free slot (there) near a given position (here). This is typically used internally to find out where to apply the cursor when it’s flying over walls.

Return value: none

Function: char * lw6ker_game_struct_to_hexa (lw6sys_context_t * sys_context, const lw6ker_game_struct_t * game_struct)

sys_context: global system context

game_struct: the game struct to convert

Converts a map to something that is later readable by lw6ker_game_struct_from_hexa to reproduce the exact same map. Just a serializer.

Return value: a newly allocated pointer, NULL if conversion failed.

Function: lw6ker_game_struct_t * lw6ker_game_struct_from_hexa (lw6sys_context_t * sys_context, const char * hexa, const lw6map_level_t * level)

sys_context: global system context

hexa: an hexadecimal ASCII string, created by lw6ker_game_struct_to_hexa

level: the level this game_struct is bounded to

Constructs a game struct from an hexadecimal string generated by lw6ker_game_struct_to_hexa. Just an un-serializer.

Return value: a new map, might be NULL if string isn’t correct.

Function: char * lw6ker_game_state_to_hexa (lw6sys_context_t * sys_context, const lw6ker_game_state_t * game_state)

sys_context: global system context

game_state: the game state to convert

Converts a map to something that is later readable by lw6ker_game_state_from_hexa to reproduce the exact same map. Just a serializer.

Return value: a newly allocated pointer, NULL if conversion failed.

Function: lw6ker_game_state_t * lw6ker_game_state_from_hexa (lw6sys_context_t * sys_context, const char * hexa, const lw6ker_game_struct_t * game_struct)

sys_context: global system context

hexa: an hexadecimal ASCII string, created by lw6ker_game_state_to_hexa

game_struct: the game_struct this game_state is bounded to

Constructs a game state from an hexadecimal string generated by lw6ker_game_state_to_hexa. Just an un-serializer.

Return value: a new map, might be NULL if string isn’t correct.

Function: int lw6ker_move_get_best_next_pos (lw6sys_context_t * sys_context, const lw6ker_game_state_t * game_state, lw6sys_xyz_t * next_pos, lw6sys_xyz_t * current_pos, int team_color)

game_state: the game_state to work on

next_pos: the next position (out param)

current_pos: the current position

team_color: the team color

Tries to find the best move given a position and a team. Note that this function does not check for the presence of another fighter, it will only check walls and can even (sometimes) fail when there’s a path. The reason is that it uses the game_state at a given round and does not recalculate gradient while a real fighter has an ever-changing gradient. Whatsoever, this can be used to move cursors like they were fighters, it’s not perfect but gives a good illusion.

Return value: 1 if best place found, 0 if not.

Function: int lw6ker_score_array_update (lw6sys_context_t * sys_context, lw6ker_score_array_t * score_array, const lw6ker_game_state_t * game_state)

sys_context: global system context

score_array: the score array to modify

game_state: the game_state to get the information from

Updates a score array, that is, calculates all scores, so that they can be displayed, for instance.

Return value: 1 on success, 0 on failure.

Function: void lw6ker_team_mask_get (lw6sys_context_t * sys_context, u_int32_t * even, u_int32_t * odd, int32_t round)

sys_context: global system context

even: even team mask (out param)

odd: odd team mask (out param)

round: round concerned

Returns a default team mask for a given round, even and odd will contain ready to use masks (for spread and move functions for instance).

Return value: none.

Function: void lw6ker_team_mask_best (lw6sys_context_t * sys_context, u_int32_t * even, u_int32_t * odd, lw6ker_game_state_t * game_state)

sys_context: global system context

even: even team mask (out param)

odd: odd team mask (out param)

game_state: the game_state concerned

Returns an optimal team mask for a given round, even and odd will contain ready to use masks (for spread and move functions for instance). The difference with the default team mask is that this one will test for which teams are present and try and manage to find an equilibrated set of odd/even teams.

Return value: none.

Function: int lw6ker_team_mask_is_concerned (lw6sys_context_t * sys_context, int team_color, u_int32_t team_mask)

sys_context: global system context

team_color: color index

team_mask: team mask

Tells wether a given team is concerned by a team mask.

Return value: 1 if concerned, 0 if not.

Function: int lw6ker_team_mask_color2mask (lw6sys_context_t * sys_context, int team_color)

team_color: color index

Gives the mask corresponding to a given color.

Return value: bitwise mask.

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

sys_context: global system context

mode: test mode (bitmask)

Registers all tests for the libker module. Thoses tests Will perform deep checksums and *really* check many things. If this passes, the algorithm is fine. What could make it fail is a serious bug and/or some weird combination of endianess, byte alignment... *

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

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

sys_context: global system context

mode: test mode (bitmask)

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

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

Struct: lw6ker_cursor_control_s

Contains a cursor controls state, basically a cursor is a position plus a fire and fire2 booleans.

Member of lw6ker_cursor_control_s: pos

Type: lw6sys_xyz_t

Definition: lw6sys_xyz_t lw6ker_cursor_control_s::pos

Cursor position, z isn’t relevant for now.

Member of lw6ker_cursor_control_s: fire

Type: int

Definition: int lw6ker_cursor_control_s::fire

Fire, 1 if primary weapon must be used.

Member of lw6ker_cursor_control_s: fire2

Type: int

Definition: int lw6ker_cursor_control_s::fire2

Fire2, 1 if secondary weapon must be used.

Struct: lw6ker_cursor_s

Data about a given cursor.

Member of lw6ker_cursor_s: node_id

Type: u_int64_t

Definition: u_int64_t lw6ker_cursor_s::node_id

The id of the node this cursor belongs to.

Member of lw6ker_cursor_s: cursor_id

Type: u_int16_t

Definition: u_int16_t lw6ker_cursor_s::cursor_id

The id of this cursor.

Member of lw6ker_cursor_s: letter

Type: char

Definition: char lw6ker_cursor_s::letter

ASCII code of the letter associated to the cursor.

Member of lw6ker_cursor_s: enabled

Type: int

Definition: int lw6ker_cursor_s::enabled

Wether the cursor is enabled/active or not.

Member of lw6ker_cursor_s: team_color

Type: int

Definition: int lw6ker_cursor_s::team_color

Team associated with this cursor.

Member of lw6ker_cursor_s: pos

Type: lw6sys_xyz_t

Definition: lw6sys_xyz_t lw6ker_cursor_s::pos

Cursor position, z isn’t relevant for now.

Member of lw6ker_cursor_s: fire

Type: int

Definition: int lw6ker_cursor_s::fire

Primary fire button state.

Member of lw6ker_cursor_s: fire2

Type: int

Definition: int lw6ker_cursor_s::fire2

Alternate fire button state.

Member of lw6ker_cursor_s: apply_pos

Type: lw6sys_xyz_t

Definition: lw6sys_xyz_t lw6ker_cursor_s::apply_pos

Position to apply cursor on. Problem follows: cursor might be hanging on a wall, somewhere fighters can’t go. In that case an alternate position is find, usually the closest free space. But this can take time to calculate so we cache this value here, as it is convenient to have it at hand.

Member of lw6ker_cursor_s: pot_offset

Type: int32_t

Definition: int32_t lw6ker_cursor_s::pot_offset

Potential offset. Whenever the cursor is applied to some place, one can add a potential to it, this can be used to make some cursor more attractive than others.

Struct: lw6ker_fighter_s

Contains the parameters of a fighter, one of those little squares that are that at the very heart of Liquid War.

Member of lw6ker_fighter_s: team_color

Type: u_int32_t

Definition: u_int32_t lw6ker_fighter_s::team_color

Team color from 0 to 9, -1 if invalid.

Member of lw6ker_fighter_s: last_direction

Type: int32_t

Definition: int32_t lw6ker_fighter_s::last_direction

Last direction this fighter used, this is important for in some cases we want to know where the fighter was heading before, our current choice might rely on previous state.

Member of lw6ker_fighter_s: health

Type: int32_t

Definition: int32_t lw6ker_fighter_s::health

Fighter health from 0 to 10000.

Member of lw6ker_fighter_s: act_counter

Type: int32_t

Definition: int32_t lw6ker_fighter_s::act_counter

This counter is used to handle speed up/slow down. At each round it’s incremented, whenever it reaches 100 then the fighter really acts. Basically, there’s a Bresenham algorithm behind all that.

Member of lw6ker_fighter_s: pad

Type: int32_t

Definition: int32_t lw6ker_fighter_s::pad

Free for later use.

Member of lw6ker_fighter_s: pos

Type: lw6sys_xyz_t

Definition: lw6sys_xyz_t lw6ker_fighter_s::pos

Fighter position.

Struct: lw6ker_game_state_s

Game structure containing all changeable data state, this will hold the fighter positions, their health, the cursors position, the gradient, anything that is dynamic. Note that this structure is a wrapper over the internal structure which contains the real members, the first two members need be the same as it is casted internally.

Member of lw6ker_game_state_s: id

Type: u_int32_t

Definition: u_int32_t lw6ker_game_state_s::id

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

Member of lw6ker_game_state_s: game_struct

Type: lw6ker_game_struct_t *

Definition: lw6ker_game_struct_t* lw6ker_game_state_s::game_struct

Pointer on the game non-mutable structure, which holds the data that is never changed within a game.

Struct: lw6ker_game_struct_s

Game struct is very similar to the level struct of the lw6map module. Indeed, it’s immutable and won’t change during the game. The difference with lw6map_level is that game_struct is algorithm aware and has many tricks, special internals, cached data, so that it speeds up the overall algorithm. In fact it contains everything lw6ker_game_state needs to have but need not change during the game. The 3 first members, id, level, rules are the same as the internal _lw6ker_game_struct_t structure. The rest of it is hidden. The program will cast from lw6ker_game_struct_t to _lw6ker_game_struct_t internally.

Member of lw6ker_game_struct_s: id

Type: u_int32_t

Definition: u_int32_t lw6ker_game_struct_s::id

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

Member of lw6ker_game_struct_s: level

Type: lw6map_level_t *

Definition: lw6map_level_t* lw6ker_game_struct_s::level

Pointer on the level source structure. This one might still retain informations we don’t want to duplicate here, for instance the textures, which are of no use for the core algorithm so are pointless to backup here, but are still of interest for high-level functions such as display stuff.

Member of lw6ker_game_struct_s: rules

Type: lw6map_rules_t

Definition: lw6map_rules_t lw6ker_game_struct_s::rules

Game rules, this is just a cached copy to avoid derefencing the level pointer any time we need to query a parameter.

Struct: lw6ker_score_array_s

This is an array which contains all scores for all teams, it’s calculated from game_state and should be used read only by code which is not within lw6ker.

Member of lw6ker_score_array_s: active_fighters

Type: int

Definition: int lw6ker_score_array_s::active_fighters

Number of fighters on the battlefield.

Member of lw6ker_score_array_s: nb_scores

Type: int

Definition: int lw6ker_score_array_s::nb_scores

Number of score items. This can be greater than the number of active teams, since it retains informations about teams which have disappeared.

Member of lw6ker_score_array_s: scores

Type: lw6ker_score_t

Definition: lw6ker_score_t lw6ker_score_array_s::scores[LW6MAP_NB_TEAM_COLORS]

Scores for each team, they are sorted, the first one with index 0 is the current winner, then all other teams follow, the last one being Mr Looser.

Struct: lw6ker_score_s

Stores the score information about a team, this structure is used to get informations from the game, and display them.

Member of lw6ker_score_s: has_been_active

Type: int

Definition: int lw6ker_score_s::has_been_active

Wether this team (this color) has been active at some point during the game. This is important for at score time, many teams might have been disabled, this is typical of dead teams in the LW5 last player wins scheme. It can also happen in network games after a team leaves. Note that this way of counting active teams does not allow fine grain knowledge of who played, for the yellow team might have been played by different nodes through a single game session.

Member of lw6ker_score_s: team_color

Type: int

Definition: int lw6ker_score_s::team_color

The color of the team this score is about.

Member of lw6ker_score_s: fighters_percent

Type: int

Definition: int lw6ker_score_s::fighters_percent

Percentage of fighters for this team. The global score array object will take care of making the sum of fighters_percent be exactly 100, regardless of exactitude, it will round this number to make a nice total and hide rounding errors.

Member of lw6ker_score_s: fighters_absolute

Type: int

Definition: int lw6ker_score_s::fighters_absolute

Absolute number of fighters for this team.

Member of lw6ker_score_s: fighters_ratio

Type: float

Definition: float lw6ker_score_s::fighters_ratio

One of the rare float in lw6ker, only for eye candy, this is the equivalent of fighters_percent but as a float between 0.0f and 1.0f. It gives the possibility of more precise graphical displays, will its integer companion value is usefull for writing down scores.

Member of lw6ker_score_s: frags

Type: int

Definition: int lw6ker_score_s::frags

Number of frags. Note that depending on game rules, this can have very different meanings.

Member of lw6ker_score_s: consolidated_percent

Type: int

Definition: int lw6ker_score_s::consolidated_percent

OK, this is probably the most non-intuitive number but still the most usefull. It will show a percentage that is greater as we estimate the team in a stronger position. For instance, it can be higher if the team has very few fighters on the field but has a great number of frags. The one who has the greatest number here is the winner.


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