Mercurial > molko

annotate doc/docs/dev/api/core/game.md @ 312:4ea0f035f712

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc: update according to new game API
author David Demelier <markand@malikania.fr>
date Thu, 09 Sep 2021 15:30:07 +0200
parents 196264679079
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
253
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
1 # Module: game
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
2
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
3 Synopsis
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
4
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
5 ```c
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
6 #include <core/game.h>
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
7 ```
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
8
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
9 Main game loop and states.
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
10
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
11 This module offers a global game structure that contain a [state](state.md). It
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
12 is designed to help switching game states and inhibit some of the functions when
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
13 necessary.
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
14
312
4ea0f035f712 doc: update according to new game API
David Demelier <markand@malikania.fr>
parents: 298
diff changeset
15 States are pushed and removed from the stack as a LIFO queue, the last pushed
4ea0f035f712 doc: update according to new game API
David Demelier <markand@malikania.fr>
parents: 298
diff changeset
16 state will be the first state to be removed.
253
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
17
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
18 The main loop use a constant frame rate mechanism based on the screen refresh
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
19 rate if supported, otherwise it use a default frame rate of 60hz. In any case,
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
20 the frame rate is capped in the main loop and the elapsed time is measured
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
21 accordingly to update the game at constant speed no matter the refresh rate is
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
22 present.
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
23
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
24 Since only one game must be present at a time, a global `game` variable is
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
25 available for convenience to not carrying it everywhere.
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
26
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
27 ## Globals
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
28
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
29 | Variable | Type |
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
30 |----------|---------------|
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
31 | `game` | `struct game` |
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
32
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
33 ## Structs
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
34
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
35 ### game
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
36
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
37 Game structure.
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
38
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
39 | Field | Access | Type |
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
40 |---------------------------|--------|------------------|
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
41 | [inhibit](#inhibit) | (+) | `enum inhibit` |
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
42
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
43 #### inhibit
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
44
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
45 Current inhibit flags set, see [inhibit](inhibit.md) for more information.
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
46
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
47 ## Functions
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
48
312
4ea0f035f712 doc: update according to new game API
David Demelier <markand@malikania.fr>
parents: 298
diff changeset
49 ### game\_init
253
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
50
312
4ea0f035f712 doc: update according to new game API
David Demelier <markand@malikania.fr>
parents: 298
diff changeset
51 Initialize the game. This isn't required unless [game_quit](#game_quit) was
4ea0f035f712 doc: update according to new game API
David Demelier <markand@malikania.fr>
parents: 298
diff changeset
52 called.
253
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
53
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
54 ```c
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
55 void
312
4ea0f035f712 doc: update according to new game API
David Demelier <markand@malikania.fr>
parents: 298
diff changeset
56 game_init(void)
253
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
57 ```
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
58
312
4ea0f035f712 doc: update according to new game API
David Demelier <markand@malikania.fr>
parents: 298
diff changeset
59 ### game\_push
4ea0f035f712 doc: update according to new game API
David Demelier <markand@malikania.fr>
parents: 298
diff changeset
60
4ea0f035f712 doc: update according to new game API
David Demelier <markand@malikania.fr>
parents: 298
diff changeset
61 Push `state` into the stack. If there is a current running state, it is
4ea0f035f712 doc: update according to new game API
David Demelier <markand@malikania.fr>
parents: 298
diff changeset
62 suspended through the defined callback.
4ea0f035f712 doc: update according to new game API
David Demelier <markand@malikania.fr>
parents: 298
diff changeset
63
4ea0f035f712 doc: update according to new game API
David Demelier <markand@malikania.fr>
parents: 298
diff changeset
64 The argument `state` must remain valid until the lifetime of the game.
4ea0f035f712 doc: update according to new game API
David Demelier <markand@malikania.fr>
parents: 298
diff changeset
65
4ea0f035f712 doc: update according to new game API
David Demelier <markand@malikania.fr>
parents: 298
diff changeset
66 ```c
4ea0f035f712 doc: update according to new game API
David Demelier <markand@malikania.fr>
parents: 298
diff changeset
67 void
4ea0f035f712 doc: update according to new game API
David Demelier <markand@malikania.fr>
parents: 298
diff changeset
68 game_push(struct state *state)
4ea0f035f712 doc: update according to new game API
David Demelier <markand@malikania.fr>
parents: 298
diff changeset
69 ```
4ea0f035f712 doc: update according to new game API
David Demelier <markand@malikania.fr>
parents: 298
diff changeset
70
4ea0f035f712 doc: update according to new game API
David Demelier <markand@malikania.fr>
parents: 298
diff changeset
71 ### game\_pop
4ea0f035f712 doc: update according to new game API
David Demelier <markand@malikania.fr>
parents: 298
diff changeset
72
4ea0f035f712 doc: update according to new game API
David Demelier <markand@malikania.fr>
parents: 298
diff changeset
73 Remove the last state and invoke finalizer callbacks (end, finish). If there is
4ea0f035f712 doc: update according to new game API
David Demelier <markand@malikania.fr>
parents: 298
diff changeset
74 a previous state into the stack, it is resumed through the defined callback.
4ea0f035f712 doc: update according to new game API
David Demelier <markand@malikania.fr>
parents: 298
diff changeset
75
4ea0f035f712 doc: update according to new game API
David Demelier <markand@malikania.fr>
parents: 298
diff changeset
76 ```c
4ea0f035f712 doc: update according to new game API
David Demelier <markand@malikania.fr>
parents: 298
diff changeset
77 void
4ea0f035f712 doc: update according to new game API
David Demelier <markand@malikania.fr>
parents: 298
diff changeset
78 game_pop(void)
4ea0f035f712 doc: update according to new game API
David Demelier <markand@malikania.fr>
parents: 298
diff changeset
79 ```
4ea0f035f712 doc: update according to new game API
David Demelier <markand@malikania.fr>
parents: 298
diff changeset
80
4ea0f035f712 doc: update according to new game API
David Demelier <markand@malikania.fr>
parents: 298
diff changeset
81 ### game\_handle
253
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
82
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
83 Handle the event `ev` into the current state.
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
84
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
85 ```c
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
86 void
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
87 game_handle(const union event *ev)
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
88 ```
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
89
312
4ea0f035f712 doc: update according to new game API
David Demelier <markand@malikania.fr>
parents: 298
diff changeset
90 ### game\_update
253
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
91
312
4ea0f035f712 doc: update according to new game API
David Demelier <markand@malikania.fr>
parents: 298
diff changeset
92 Update the current state with `ticks` (in milliseconds) since last frame.
253
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
93
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
94 ```c
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
95 void
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
96 game_update(unsigned int ticks)
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
97 ```
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
98
312
4ea0f035f712 doc: update according to new game API
David Demelier <markand@malikania.fr>
parents: 298
diff changeset
99 ### game\_draw
253
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
100
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
101 Draw the current state.
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
102
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
103 ```c
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
104 void
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
105 game_draw(void)
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
106 ```
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
107
312
4ea0f035f712 doc: update according to new game API
David Demelier <markand@malikania.fr>
parents: 298
diff changeset
108 ### game\_loop
253
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
109
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
110 Start a blocking loop that call in order [game_handle](#game_handle),
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
111 [game_update](#game_update) and [game_draw](#game_draw) while keeping a constant
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
112 framerate.
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
113
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
114 ```c
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
115 void
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
116 game_loop(void)
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
117 ```
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
118
312
4ea0f035f712 doc: update according to new game API
David Demelier <markand@malikania.fr>
parents: 298
diff changeset
119 ### game\_quit
253
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
120
312
4ea0f035f712 doc: update according to new game API
David Demelier <markand@malikania.fr>
parents: 298
diff changeset
121 Destroy all states.
253
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
122
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
123 Even if you don't use [game_loop](#game_loop) you should call this function
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
124 because it will close state resources.
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
125
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
126 !!! caution
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
127 If you call this function from a state itself, you must return immediately
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
128 because the state will be finalized immediately.
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
129
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
130 ```c
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
131 void
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
132 game_quit(void)
c4da052c0def core: goodbye doxygen
David Demelier <markand@malikania.fr>
parents:
diff changeset
133 ```