Mercurial > molko

comparison 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
comparison
equal deleted inserted replaced
311:f10fd1293a7e 312:4ea0f035f712
10 10
11 This module offers a global game structure that contain a [state](state.md). It 11 This module offers a global game structure that contain a [state](state.md). It
12 is designed to help switching game states and inhibit some of the functions when 12 is designed to help switching game states and inhibit some of the functions when
13 necessary. 13 necessary.
14 14
15 In contrast to popular engines, states are not stacked and only one is used at a 15 States are pushed and removed from the stack as a LIFO queue, the last pushed
16 time. Switching states mean that the current state will run until next frame and 16 state will be the first state to be removed.
17 will be closed afterwards.
18 17
19 The main loop use a constant frame rate mechanism based on the screen refresh 18 The main loop use a constant frame rate mechanism based on the screen refresh
20 rate if supported, otherwise it use a default frame rate of 60hz. In any case, 19 rate if supported, otherwise it use a default frame rate of 60hz. In any case,
21 the frame rate is capped in the main loop and the elapsed time is measured 20 the frame rate is capped in the main loop and the elapsed time is measured
22 accordingly to update the game at constant speed no matter the refresh rate is 21 accordingly to update the game at constant speed no matter the refresh rate is
38 Game structure. 37 Game structure.
39 38
40 | Field | Access | Type | 39 | Field | Access | Type |
41 |---------------------------|--------|------------------| 40 |---------------------------|--------|------------------|
42 | [inhibit](#inhibit) | (+) | `enum inhibit` | 41 | [inhibit](#inhibit) | (+) | `enum inhibit` |
43 | [state](#state) | (+&?) | `struct state *` |
44 | [state_next](#state_next) | (+&?) | `struct state *` |
45 42
46 #### inhibit 43 #### inhibit
47 44
48 Current inhibit flags set, see [inhibit](inhibit.md) for more information. 45 Current inhibit flags set, see [inhibit](inhibit.md) for more information.
49 46
50 #### state
51
52 Current state running.
53
54 #### state\_next
55
56 Optional next state to be changed in next frame loop.
57
58 ## Functions 47 ## Functions
59 48
60 ### game\_switch 49 ### game\_init
61 50
62 Set `state` for the next frame. 51 Initialize the game. This isn't required unless [game_quit](#game_quit) was
63 52 called.
64 The state will only be effective after the next call to
65 [game_update](#game_update).
66
67 If argument `quick` is non-zero, the state is changed immediately and the
68 current state code should immediately return.
69 53
70 ```c 54 ```c
71 void 55 void
72 game_switch(struct state *state, int quick) 56 game_init(void)
73 ``` 57 ```
74 58
75 #### game\_handle 59 ### game\_push
60
61 Push `state` into the stack. If there is a current running state, it is
62 suspended through the defined callback.
63
64 The argument `state` must remain valid until the lifetime of the game.
65
66 ```c
67 void
68 game_push(struct state *state)
69 ```
70
71 ### game\_pop
72
73 Remove the last state and invoke finalizer callbacks (end, finish). If there is
74 a previous state into the stack, it is resumed through the defined callback.
75
76 ```c
77 void
78 game_pop(void)
79 ```
80
81 ### game\_handle
76 82
77 Handle the event `ev` into the current state. 83 Handle the event `ev` into the current state.
78 84
79 ```c 85 ```c
80 void 86 void
81 game_handle(const union event *ev) 87 game_handle(const union event *ev)
82 ``` 88 ```
83 89
84 #### game\_update 90 ### game\_update
85 91
86 Update the current state with `ticks` since last frame. 92 Update the current state with `ticks` (in milliseconds) since last frame.
87 93
88 ```c 94 ```c
89 void 95 void
90 game_update(unsigned int ticks) 96 game_update(unsigned int ticks)
91 ``` 97 ```
92 98
93 #### game\_draw 99 ### game\_draw
94 100
95 Draw the current state. 101 Draw the current state.
96 102
97 ```c 103 ```c
98 void 104 void
99 game_draw(void) 105 game_draw(void)
100 ``` 106 ```
101 107
102 #### game\_loop 108 ### game\_loop
103 109
104 Start a blocking loop that call in order [game_handle](#game_handle), 110 Start a blocking loop that call in order [game_handle](#game_handle),
105 [game_update](#game_update) and [game_draw](#game_draw) while keeping a constant 111 [game_update](#game_update) and [game_draw](#game_draw) while keeping a constant
106 framerate. 112 framerate.
107 113
108 ```c 114 ```c
109 void 115 void
110 game_loop(void) 116 game_loop(void)
111 ``` 117 ```
112 118
113 #### game\_stop 119 ### game\_quit
114 120
115 Destroy both next and current state if any. 121 Destroy all states.
116 122
117 Even if you don't use [game_loop](#game_loop) you should call this function 123 Even if you don't use [game_loop](#game_loop) you should call this function
118 because it will close state resources. 124 because it will close state resources.
119 125
120 !!! caution 126 !!! caution