.Dd $Mdocdate$
.Dt MLK-ACTION 3
.Os
.Sh NAME
.Nm mlk-action
.Nd generic in game actions
.Sh LIBRARY
libmlk-core (-lmlk-core)
.Sh SYNOPSIS
.In mlk/core/action.h
.Sh DESCRIPTION
Generic updatable and drawable actions.
.Pp
This module help creating user interaction within the gameplay by adding
actions. They have the following properties:
.Pp
.Bl -dash -compact
.It
Can handle user input and events,
.It
Can be updated through the game loop,
.It
Can be drawn.
.El
.Pp
Most more high level objects can handle actions to add flexibility (like in
battles, maps, etc).
.Pp
This header defines the
.Vt "struct mlk_action" :
.Bd -literal
struct mlk_action {
	void *data;
	void (*start)(struct mlk_action *self);
	void (*handle)(struct mlk_action *self, const union mlk_event *ev);
	int (*update)(struct mlk_action *self, unsigned int ticks);
	void (*draw)(struct mlk_action *self);
	void (*end)(struct mlk_action *self);
	void (*finish)(struct mlk_action *self);
};
.Ed
.Pp
Each member function takes the original action as first argument and other
arguments after. Its fields are:
.Bl -tag
.It Va data
Optional user data.
.It Va start
This function is called when the action is going to start. User can set a
function to prepare the action especially in a sequence (see
.Xr mlk-action-script 3
for example).
.It Va handle
Handle the event
.Fa ev .
.It Va update
Update the action with the
.Fa ticks
since last frame expressed as milliseconds. The callback should return non-zero
if it is considered complete.
.It Va draw
Draw the action.
.It Va end
Called when the action was completed.
.Pp
This callback is mostly provided to allow the user doing something else once an
action is complete. Predefined actions from the framework should not use this
callback by themselves.
.It Va finish
Destroy internal resources for this action.
.Pp
Close the action before removal. This function should be used to deallocate
memory if necessary.
.El
.Sh SEE ALSO
.Xr mlk_action_draw 3 ,
.Xr mlk_action_end 3 ,
.Xr mlk_action_finish 3 ,
.Xr mlk_action_handle 3 ,
.Xr mlk_action_update 3
.Sh AUTHORS
The
.Nm
library was written by
.An David Demelier Aq Mt markand@malikania.fr .