1/****p* PawnLibs/wowcore/SELF_ID
2 * Summary
3 *   An ID of the module on which application copy is running.
4 * Synopsis
5 */
6public const SELF_ID = 0;
7/******/
8 
9/****d* PawnLibs/wowcore/MODULES_MAX
10 * Summary
11 *   How many modules there are in the assembled cube.
12 * Synopsis
13 */
14#define MODULES_MAX 8
15/******/
16 
17/****d* PawnLibs/wowcore/SCREENS_MAX
18 * Summary
19 *   How many screens there are on the each cube module.
20 * Synopsis
21 */
22#define SCREENS_MAX 3
23/******/
24 
25/****d* PawnLibs/wowcore/SENSITIVITY_MENU_CHANGE_SCRIPT
26 * Summary
27 *   How many shakes required to trigger an application quit. Shake is a
28 *   continuous significant motion which direction has been changed since the
29 *   previous recent significant motion.
30 * Synopsis
31 */
32#define SENSITIVITY_MENU_CHANGE_SCRIPT 6
33/******/
34 
35/****d* PawnLibs/wowcore/GAME_SAVE_SIZE
36 * Summary
37 *   Maximum allowed size of an application save data in cells.
38 * Synopsis
39 */
40#define GAME_SAVE_SIZE 64
41/******/
42 
43/****d* PawnLibs/wowcore/MAX_PACKET_TYPES
44 * Summary
45 *   Maximum number of an application packet types.
46 * Synopsis
47 */
48#define MAX_PACKET_TYPES 32
49/******/
50 
51/****d* PawnLibs/wowcore/MAX_PACKET_SIZE
52 * Summary
53 *   Maximum size of an application packet.
54 * Synopsis
55 */
56#define MAX_PACKET_SIZE 28
57/******/
58 
59/****s* PawnLibs/wowcore/APP_VERSION
60 * Summary
61 *   Array with named fields describing application version.
62 * Synopsis
63 */
64#define APP_VERSION [.major, .minor, .patch]
65/*
66 * Description
67 *   Fields:
68 *   * major - increment when application significantly changed
69 *   * minor - increment when new feature added
70 *   * patch - increment when bugfix shipped
71 * See also
72 *   * getAppVersion()
73 * History
74 *   * v6.0 - added
75 ******/
76 
77/****e* PawnLibs/wowcore/ON_Init
78 * Summary
79 *   Initialization handler.
80 * Synopsis
81 */
82forward ON_Init(id, size, const pkt[]);
83/*
84 * Description
85 *   Public function with such signature will be called before the application
86 *   loop starts. Useful for a globals initializations, e.g. generating level,
87 *   baking backgrounds, etc. Additionaly save data is provided.
88 * Inputs
89 *   * id - an id of the save data
90 *   * size - size of the save data in cells
91 *   * pkt[] - array with the save data
92 * See also
93 *   * GAME_SAVE_SIZE
94 *   * loadState()
95 * History
96 *   * v5.0 - provide save data in arguments
97 ******/
98 
99/****e* PawnLibs/wowcore/ON_Tick
100 * Summary
101 *   Main application loop handler.
102 * Synopsis
103 */
104forward ON_Tick();
105/*
106 * Description
107 *   Public function with such signature will be called on each iteration of an
108 *   application loop. Main application logic should be placed here. Frequency
109 *   of calls are not constant and depends on the configured framerate,
110 *   calculations and rendering complexities.
111 * See also
112 *   * ON_PhysicsTick()
113 *   * ON_Render()
114 ******/
115 
116/****e* PawnLibs/wowcore/ON_PhysicsTick
117 * Summary
118 *   Uniformly delayed loop handler.
119 * Synopsis
120 */
121forward ON_PhysicsTick();
122/*
123 * Description
124 *   Public function with such signature will be called approximately each 30
125 *   milliseconds. However time interval between calls can be larger because the
126 *   application is single threaded and complex rendering or calculation can
127 *   delay events processing. Useful for calculations requiring a time delta,
128 *   e.g. sprite movement at a constant speed.
129 ******/
130 
131/****e* PawnLibs/wowcore/ON_Packet
132 * Summary
133 *   Network packet handler.
134 * Synopsis
135 */
136forward ON_Packet(type, size, const pkt[]);
137/*
138 * Description
139 *   Public function with such signature will be called to handle a received
140 *   application packet from an another module in the cube network.
141 * Inputs
142 *   * type  - an application packet type
143 *   * size  - size of the received packet
144 *   * pkt[] - array with a message data
145 * See also
146 *   * broadcastPacket()
147 * History
148 *   * v6.0 - added
149 ******/
150 
151 
152/****e* PawnLibs/wowcore/ON_Load
153 * Summary
154 *   Asynchronous application save data handler.
155 * Synopsis
156 */
157forward ON_Load(id, size, const pkt[]);
158/*
159 * Description
160 *   Public function with such signature will be called to handle an application
161 *   save data. It is an asynchronous event so access to flash memory will not
162 *   affect an application performance.
163 * Inputs
164 *   * id - an id of the save data
165 *   * size - size of the save data in cells
166 *   * pkt[] - array with the save data
167 * See also
168 *   * GAME_SAVE_SIZE
169 *   * loadState()
170 *   * saveState()
171 * History
172 *   * v5.0 - provide data header as arguments rather than first cell
173 ******/
174 
175/****e* PawnLibs/wowcore/ON_Quit
176 * Summary
177 *   Application quit handler.
178 * Synopsis
179 */
180forward ON_Quit();
181/*
182 * Description
183 *   Public function with such signature will be called to handle an application
184 *   quit event when user did triple shake. Application can shutdown gracefully,
185 *   e.g. save state on the flash memory. Application has 1000ms to run handler
186 *   and will be termintated after that period. No more handlers will be called.
187 * See also
188 *   * saveState()
189 * History
190 *   * v5.0 - added
191 ******/
192 
193/****n* PawnLibs/wowcore/getTime
194 * Summary
195 *   Get time in milliseconds since the module start.
196 * Synopsis
197 */
198native getTime();
199/*
200 * Return value
201 *   Time in milliseconds since the module start.
202 ******/
203 
204/****n* PawnLibs/wowcore/getUserName
205 * Summary
206 *   Get the name of a user who is logined on the cube.
207 * Synopsis
208 */
209native getUserName(userName[], size = sizeof(userName));
210/*
211 * Description
212 *   Get the user name configured in the WOWCube mobile application to save
213 *   results for.
214 * Inputs
215 *   * size - size of string to keep a user name
216 * Outputs
217 *   * userName - string to keep a user name
218 * See also
219 *   * USER_NAME_LENGTH
220 ******/
221 
222/****n* PawnLibs/wowcore/quit
223 * Summary
224 *   Quit from the application.
225 * Synopsis
226 */
227native quit();
228/*
229 * See also
230 *   * SENSITIVITY_MENU_CHANGE_SCRIPT
231 ******/
232 
233/****n* PawnLibs/wowcore/toggleDebugInfo
234 * Summary
235 *   Toggle overlay with debug information. TBD - move to GFX
236 * Synopsis
237 */
238native toggleDebugInfo();
239/*
240 * Description
241 *   Debug information includes:
242 *   TBD - current information is obsolete
243 ******/
244 
245/****n* PawnLibs/wowcore/broadcastPacket
246 * Summary
247 *   Broadcast a packet over the cube network.
248 * Synopsis
249 */
250native broadcastPacket(type, const data[], size = sizeof(data));
251/*
252 * Description
253 *   TBD: routing, filtering. Packet delivery is not guaranteed. Packet types
254 *   equal or greater than MAX_PACKET_TYPES are discarded. Packet sizes greater
255 *   than MAX_PACKET_SIZE are discarded.
256 * Inputs
257 *   * type   - arbitrary packet type
258 *   * data[] - packet data to broadcast
259 *   * size   - size of the packet data in cells
260 * See also
261 *   * ON_Packet()
262 *   * MAX_PACKET_TYPES
263 *   * MAX_PACKET_SIZE
264 * History
265 *   * v6.0 - added
266 ******/
267 
268/****n* PawnLibs/wowcore/saveState
269 * Summary
270 *   Request to save an application data
271 * Synopsis
272 */
273native bool:saveState(const data[], size = sizeof(data));
274/*
275 * Description
276 *   Save user settings and/or progress on the flash to restore next time. Each
277 *   save data has an incremental ID.
278 * Inputs
279 *   * data [] - data to save
280 *   * size    - size of data in cells to save
281 * Return value
282 *   True if save was successful.
283 * See also
284 *   * GAME_SAVE_SIZE
285 *   * ON_Load()
286 *   * loadState()
287 * History
288 *   * v5.0 - fixed a bug in which only part of a data saved on the flash
289 ******/
290 
291/****n* PawnLibs/wowcore/loadState
292 * Summary
293 *   Request to load an application save data from the flash.
294 * Synopsis
295 */
296native loadState();
297/*
298 * Description
299 *   Trigger state load event. It is asynchronous so access to flash memory will
300 *   not affect an application performance.
301 * See also
302 *   * ON_Load()
303 *   * saveState()
304 ******/
305 
306/****n* PawnLibs/wowcore/random
307 * Summary
308 *   Generate random number in half-open range.
309 * Synopsis
310 */
311native random(min, max);
312/*
313 * Description
314 *   Random number generator is initialized before each application start. Seed
315 *   for initialization is generated by TRNG (True Random Number Generator).
316 * Inputs
317 *   * min - minimal value of range to generate random number
318 *   * max - maximum value of range to generate random number
319 * Return value
320 *   Pseudo random value from requested range.
321 * History
322 *   * v5.0 - fixed a bug in which random does not generate numbers in a given
323 *     range.
324 ******/
325 
326/****n* PawnLibs/wowcore/getAppVersion
327 * Summary
328 *   Get application version.
329 * Synopsis
330 */
331native getAppVersion(version[APP_VERSION]);
332/*
333 * Description
334 *   WOWCube applications follow semantic versioning scheme (see
335 *   https://semver.org). This interface allows to get version parts stored in
336 *   the cube application descriptor.
337 * Outputs
338 *   * version - structure describing application version
339 * See also
340 *   * APP_VERSION
341 * History
342 *   * v6.0 - added
343 ******/
344 
345/****f* PawnLibs/wowcore/parseByte
346 * Summary
347 *   Get arbitrary byte value from array.
348 * Synopsis
349 */
350stock parseByte(const arr[], const n)
351/*
352 * Description
353 *   Pawn works with cells which has a size of 4 bytes. Native interfaces
354 *   handling generic data like network messages have size limits for that data.
355 *   If application does not need to work with a large numbers, several values
356 *   can be packed into a single cell. This function provides interface to
357 *   extract such values from array.
358 * Inputs
359 *   * arr - array to read byte from
360 *   * n   - number of byte to read
361 * Return value
362 *   Requested byte value.
363 * See also
364 *   * broadcastPacket()
365 *   * saveState()
366 *   * ON_Load()
367 *   * ON_Packet()
368 * Source
369 */
370{
371  return ((arr[n/4] >> (8*(n%4))) & 0xFF);
372}
373/******/
374 
375