Game Extension

Extension of our API that can be used as a building block for game servers. More...

Classes
struct	GrvxMissileLaunch
	Settings of a scheduled missile launch. More...
struct	GrvxMissileObservation
	Observation of a missile. More...

Typedefs
typedef struct GrvxGame *	GrvxGameHandle
	Handle to a game. More...

Functions
GRVX_EXPORT int32_t	grvx_rnd_init_planets (GrvxPlanetsHandle planets, uint32_t *seed, double min_dist)
	Initializes planets randomly. More...
GRVX_EXPORT GrvxGameHandle	grvx_init_game (GrvxPlanetsHandle planets)
	Initializes a new game from a set of planets. More...
GRVX_EXPORT void	grvx_delete_game (GrvxGameHandle handle)
	Deletes a game instance. More...
GRVX_EXPORT int32_t	grvx_request_launch (GrvxGameHandle game, uint32_t planet_id, struct GrvxMissileLaunch *missile, double dt)
	Requests a missile launch. More...
GRVX_EXPORT struct GrvxMissileObservation *	grvx_observe_or_tick (GrvxGameHandle game, uint32_t *t)
	Returns a new observation or advances time. More...

Detailed Description

Extension of our API that can be used as a building block for game servers.

The Game module is an extension of the libgravix2 API. Games are created from a given set of planets. If not already initialized, grvx_rnd_init_planets() can be used to randomly sample the planets in the universe.

Use grvx_init_game() and grvx_delete_game() to generate and delete games. The game API is designed to encapsulate the initialization and propagation of missiles, and it introduces two new data structures: GrvxMissileLaunch and GrvxMissileObservation. The former is used to request new missile launches (see grvx_request_launch()) and the latter summarizes events at given time ticks.

Time is represented by ticks and is advanced via grvx_observe_or_tick(). A tick is an integer, however, observable events are represented as fractions of ticks.

Typedef Documentation

GrvxGameHandle

typedef struct GrvxGame* GrvxGameHandle

Handle to a game.

Games are intentionally opaque in the API and should only be referred to by their respective handle. Internals are subjects to change.

Function Documentation

grvx_delete_game()

GRVX_EXPORT void grvx_delete_game

(

GrvxGameHandle

handle

)

Deletes a game instance.

Deletes a game instance that was created with grvx_init_game(), frees allocated memory, and invalidates any pointers to GrvxMissileObservation that were returned by grvx_observe_or_tick().

Parameters

handle

The game handle.

Here is the call graph for this function:

grvx_init_game()

GRVX_EXPORT GrvxGameHandle grvx_init_game

(

GrvxPlanetsHandle

planets

)

Initializes a new game from a set of planets.

A new game is created from a set of planets.

The caller of this functions owns this new game instance and it is his/her obligation to eventually destroy it via grvx_delete_game().

Parameters

planets

Set of planets.

Returns

Game handle.

Here is the call graph for this function:

grvx_observe_or_tick()

GRVX_EXPORT struct GrvxMissileObservation* grvx_observe_or_tick	(	GrvxGameHandle	game,
		uint32_t *	t
	)

Returns a new observation or advances time.

Pings and detonations at planet surfaces are observable and a list of observations is associated with each tick. Upon calling one element of the list for the current tick is returned and is removed from the list. The current tick is written to t. If the list is empty, time is advanced by increasing the tick count by one. This updated tick is written to t and NULL is returned.

The lifetime of the returned observation is managed by the game instance. In particular, calling grvx_observe_or_tick() implicitly invalidates any previous pointers that were returned by grvx_observe_or_tick(). Calling grvx_delete_game() invalidates all pointers to GrvxMissileObservation that were returned by grvx_observe_or_tick().

Parameters

game	The game handle.
t	Updated and now current tick (time step.)

Returns

Pointer to observation or NULL.

grvx_request_launch()

GRVX_EXPORT int32_t grvx_request_launch	(	GrvxGameHandle	game,
		uint32_t	planet_id,
		struct GrvxMissileLaunch *	missile,
		double	dt
	)

Requests a missile launch.

Requests the launch of a missile at some future time step (tick.) If the request is accepted, a launch is scheduled at the given planet.

The time step of the integrator, \(h\), is set to the ratio of dt over the product of the number of integration steps between trajectory points, GRVX_INT_STEPS, and the trajectory size GRVX_TRAJECTORY_SIZE. This makes dt and the simulated time interval independent of GRVX_INT_STEPS and GRVX_TRAJECTORY_SIZE?.

Parameters

game	The game handle.
planet_id	ID of the planet.
missile	Settings of the requested missile launch.
dt	Step size of the simulation.

Returns

Zero on success.

grvx_rnd_init_planets()

GRVX_EXPORT int32_t grvx_rnd_init_planets	(	GrvxPlanetsHandle	planets,
		uint32_t *	seed,
		double	min_dist
	)

Initializes planets randomly.

Planets are randomly distributed in their universe by sampling from a distribution that is uniform on spherical surfaces. If the distance of two planets is smaller than min_dist, new positions are drawn from the distribution until all planets are (pair-wise) separated by at least the requested distance.

The number of random draws from the distribution is returned. Note that this number equals at least the number of planets and is larger whenever additional draws were needed.

The seed is updated by each draw such that two consecutive calls to grvx_rnd_init_planets() (w/o resetting seed) will return different results.

If min_dist is chosen too large, initializing can cause many iterations and can even block indefinitely. As a rule of thumb, \(\cos d/2 \gg 1 - 2/n\) or \(d \ll 4 / \sqrt{n}\) where \(d\) is min_dist in radians, \(n\) is the number of planets, and \(2 \pi (1 - \cos r)\) is the area of a small circle with radius \(r\) on a unit sphere.

Parameters

planets	The planets handle.
seed	Seed value used for generating random values.
min_dist	Minimum distance between two planets.

Returns

Number of random draws from the distribution.