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 *   * ON_Shake()
232 ******/
233 
234/****n* PawnLibs/wowcore/toggleDebugInfo
235 * Summary
236 *   Toggle overlay with debug information. TBD - move to GFX
237 * Synopsis
238 */
239native toggleDebugInfo();
240/*
241 * Description
242 *   Debug information includes:
243 *   TBD - current information is obsolete
244 ******/
245 
246/****n* PawnLibs/wowcore/broadcastPacket
247 * Summary
248 *   Broadcast a packet over the cube network.
249 * Synopsis
250 */
251native broadcastPacket(type, const data[], size = sizeof(data));
252/*
253 * Description
254 *   TBD: routing, filtering. Packet delivery is not guaranteed. Packet types
255 *   equal or greater than MAX_PACKET_TYPES are discarded. Packet sizes greater
256 *   than MAX_PACKET_SIZE are discarded.
257 * Inputs
258 *   * type   - arbitrary packet type
259 *   * data[] - packet data to broadcast
260 *   * size   - size of the packet data in cells
261 * See also
262 *   * ON_Packet()
263 *   * MAX_PACKET_TYPES
264 *   * MAX_PACKET_SIZE
265 * History
266 *   * v6.0 - added
267 ******/
268 
269/****n* PawnLibs/wowcore/saveState
270 * Summary
271 *   Request to save an application data
272 * Synopsis
273 */
274native bool:saveState(const data[], size = sizeof(data));
275/*
276 * Description
277 *   Save user settings and/or progress on the flash to restore next time. Each
278 *   save data has an incremental ID.
279 * Inputs
280 *   * data [] - data to save
281 *   * size    - size of data in cells to save
282 * Return value
283 *   True if save was successful.
284 * See also
285 *   * GAME_SAVE_SIZE
286 *   * ON_Load()
287 *   * loadState()
288 * History
289 *   * v5.0 - fixed a bug in which only part of a data saved on the flash
290 ******/
291 
292/****n* PawnLibs/wowcore/loadState
293 * Summary
294 *   Request to load an application save data from the flash.
295 * Synopsis
296 */
297native loadState();
298/*
299 * Description
300 *   Trigger state load event. It is asynchronous so access to flash memory will
301 *   not affect an application performance.
302 * See also
303 *   * ON_Load()
304 *   * saveState()
305 ******/
306 
307/****n* PawnLibs/wowcore/random
308 * Summary
309 *   Generate random number in half-open range.
310 * Synopsis
311 */
312native random(min, max);
313/*
314 * Description
315 *   Random number generator is initialized before each application start. Seed
316 *   for initialization is generated by TRNG (True Random Number Generator).
317 * Inputs
318 *   * min - minimal value of range to generate random number
319 *   * max - maximum value of range to generate random number
320 * Return value
321 *   Pseudo random value from requested range.
322 * History
323 *   * v5.0 - fixed a bug in which random does not generate numbers in a given
324 *     range.
325 ******/
326 
327/****n* PawnLibs/wowcore/getAppVersion
328 * Summary
329 *   Get application version.
330 * Synopsis
331 */
332native getAppVersion(version[APP_VERSION]);
333/*
334 * Description
335 *   WOWCube applications follow semantic versioning scheme (see
336 *   https://semver.org). This interface allows to get version parts stored in
337 *   the cube application descriptor.
338 * Outputs
339 *   * version - structure describing application version
340 * See also
341 *   * APP_VERSION
342 * History
343 *   * v6.0 - added
344 ******/
345 
346/****f* PawnLibs/wowcore/parseByte
347 * Summary
348 *   Get arbitrary byte value from array.
349 * Synopsis
350 */
351stock parseByte(const arr[], const n)
352/*
353 * Description
354 *   Pawn works with cells which has a size of 4 bytes. Native interfaces
355 *   handling generic data like network messages have size limits for that data.
356 *   If application does not need to work with a large numbers, several values
357 *   can be packed into a single cell. This function provides interface to
358 *   extract such values from array.
359 * Inputs
360 *   * arr - array to read byte from
361 *   * n   - number of byte to read
362 * Return value
363 *   Requested byte value.
364 * See also
365 *   * broadcastPacket()
366 *   * saveState()
367 *   * ON_Load()
368 *   * ON_Packet()
369 * Source
370 */
371{
372  return ((arr[n/4] >> (8*(n%4))) & 0xFF);
373}
374/******/
375 
376