Mercurial > molko

comparison libmlk-core/core/script.h @ 243:71b3b7036de7

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
misc: lot of cleanups, - prefix libraries with libmlk, - move assets from source directories closes #2520, - prefix header guards closes #2519
author David Demelier <markand@malikania.fr>
date Sat, 28 Nov 2020 22:37:30 +0100
parents libcore/core/script.h@b386d25832c8
children c4da052c0def
comparison
equal deleted inserted replaced
242:4c24604efcab 243:71b3b7036de7
1 /*
2 * script.h -- convenient sequence of actions
3 *
4 * Copyright (c) 2020 David Demelier <markand@malikania.fr>
5 *
6 * Permission to use, copy, modify, and/or distribute this software for any
7 * purpose with or without fee is hereby granted, provided that the above
8 * copyright notice and this permission notice appear in all copies.
9 *
10 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
11 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
12 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
13 * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
14 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
15 * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
16 * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17 */
18
19 #ifndef MOLKO_CORE_SCRIPT_H
20 #define MOLKO_CORE_SCRIPT_H
21
22 /**
23 * \file script.h
24 * \brief Convenient sequence of actions.
25 * \ingroup actions
26 *
27 * Those routines wrap individual actions into a sequence of actions into an
28 * action itself.
29 *
30 * This is convenient for scenarios where you need to specify several
31 * sequential actions that neet to wait before continuing.
32 *
33 * In a nutshell, to write a scenario you should:
34 *
35 * 1. Create a script with see \ref script_init,
36 * 2. Create one or more actions and append with \ref script_append,
37 *
38 * \warning You must always call \ref script_init before using this object.
39 */
40
41 #include <stdbool.h>
42 #include <stddef.h>
43
44 struct action;
45
46 union event;
47
48 /**
49 * \brief Maximum number of actions in a script.
50 */
51 #define SCRIPT_ACTION_MAX (128)
52
53 /**
54 * \brief Sequence of actions and state holder.
55 *
56 * Setup the array actions within the structure for each action you want to run
57 * in order. You can use the convenient \ref script_append instead. If you do
58 * manually don't forget to adjust actionsz field accordingly.
59 */
60 struct script {
61 struct action *actions[SCRIPT_ACTION_MAX]; /*!< (+&?) Array of actions. */
62 size_t actionsz; /*!< (-) Number of actions in array. */
63 size_t cur; /*!< (-) Current action index.*/
64 };
65
66 /**
67 * Initialize a script.
68 *
69 * This is not necessary if you zero'ed the structure.
70 *
71 * \pre s != NULL
72 * \param s the script
73 */
74 void
75 script_init(struct script *s);
76
77 /**
78 * Append a new action to the script.
79 *
80 * The action must be kept alive until the script is no longer used.
81 *
82 * \pre s != NULL
83 * \pre a != NULL
84 * \param s the script
85 * \param a the action to reference
86 * \return false if unable to append
87 */
88 bool
89 script_append(struct script *s, struct action *a);
90
91 /**
92 * Handle the event into the current action.
93 *
94 * \pre s != NULL
95 * \pre ev != NULL
96 * \param s the script
97 * \param ev the event
98 */
99 void
100 script_handle(struct script *s, const union event *ev);
101
102 /**
103 * Update the current action.
104 *
105 * \pre s != NULL
106 * \param s the script
107 * \param ticks the number of milliseconds since last frame
108 * \return true if the script completed
109 */
110 bool
111 script_update(struct script *s, unsigned int ticks);
112
113 /**
114 * Draw the current action.
115 *
116 * \pre s != NULL
117 * \param s the script
118 */
119 void
120 script_draw(struct script *s);
121
122 /**
123 * Tells if the script is terminated.
124 *
125 * \pre s != NULL
126 * \param s the script
127 * \return true if all action were completed
128 */
129 bool
130 script_completed(const struct script *s);
131
132 /**
133 * Destroy all the actions into the script.
134 *
135 * \pre s != NULL
136 * \param s the script
137 */
138 void
139 script_finish(struct script *s);
140
141 /**
142 * Create an action from the script itself for use into the game.
143 *
144 * The script must be kept alive until the action is no longer needed.
145 *
146 * \pre s != NULL
147 * \pre dst != NULL
148 * \param s the script
149 * \param dst the action to build with the script
150 */
151 void
152 script_action(struct script *s, struct action *dst);
153
154 #endif /* !MOLKO_CORE_SCRIPT_H */