SDK 6.3/PAWN/Core

Official WOWCube SDK documentation. SDK 6.3, PAWN API. Generated from the canonical SDK headers — do not edit by hand; regenerate from source.

Constants and defines

MODULES_MAX

Syntax:

#define MODULES_MAX 8

Description:

How many modules there are in the assembled cube.

SCREENS_MAX

Syntax:

#define SCREENS_MAX 3

Description:

How many screens there are on the each cube module.

SENSITIVITY_MENU_CHANGE_SCRIPT

Syntax:

#define SENSITIVITY_MENU_CHANGE_SCRIPT 6

Description:

How many shakes required to trigger an application quit. Shake is a

continuous significant motion which direction has been changed since the

previous recent significant motion.

GAME_SAVE_SIZE

Syntax:

#define GAME_SAVE_SIZE 64

Description:

Maximum allowed size of an application save data in cells.

MAX_PACKET_TYPES

Syntax:

#define MAX_PACKET_TYPES 32

Description:

Maximum number of an application packet types.

MAX_PACKET_SIZE

Syntax:

#define MAX_PACKET_SIZE 28

Description:

Maximum size of an application packet.

Data structures

APP_VERSION

Syntax:

#define APP_VERSION [.major, .minor, .patch]

Description:

Array with named fields describing application version.

Fields:

• major - increment when application significantly changed
• minor - increment when new feature added
• patch - increment when bugfix shipped

See also: getAppVersion()

History:

v6.0 - added

Event handlers

ON_Init

Syntax:

forward ON_Init(id, size, const pkt[]);

Description:

Initialization handler.

Public function with such signature will be called before the application

loop starts. Useful for a globals initializations, e.g. generating level,

baking backgrounds, etc. Additionaly save data is provided.

Arguments:

id

an id of the save data

size

size of the save data in cells

pkt[]

array with the save data

See also: GAME_SAVE_SIZE, loadState()

History:

v5.0 - provide save data in arguments

ON_Tick

Syntax:

forward ON_Tick();

Description:

Main application loop handler.

Public function with such signature will be called on each iteration of an

application loop. Main application logic should be placed here. Frequency

of calls are not constant and depends on the configured framerate,

calculations and rendering complexities.

See also: ON_PhysicsTick(), ON_Render()

ON_PhysicsTick

Syntax:

forward ON_PhysicsTick();

Description:

Uniformly delayed loop handler.

Public function with such signature will be called approximately each 30

milliseconds. However time interval between calls can be larger because the

application is single threaded and complex rendering or calculation can

delay events processing. Useful for calculations requiring a time delta,

e.g. sprite movement at a constant speed.

ON_Packet

Syntax:

forward ON_Packet(type, size, const pkt[]);

Description:

Network packet handler.

Public function with such signature will be called to handle a received

application packet from an another module in the cube network.

Arguments:

type

an application packet type

size

size of the received packet

pkt[]

array with a message data

See also: broadcastPacket()

History:

v6.0 - added

ON_Load

Syntax:

forward ON_Load(id, size, const pkt[]);

Description:

Asynchronous application save data handler.

Public function with such signature will be called to handle an application

save data. It is an asynchronous event so access to flash memory will not

affect an application performance.

Arguments:

id

an id of the save data

size

size of the save data in cells

pkt[]

array with the save data

See also: GAME_SAVE_SIZE, loadState(), saveState()

History:

v5.0 - provide data header as arguments rather than first cell

ON_Quit

Syntax:

forward ON_Quit();

Description:

Application quit handler.

Public function with such signature will be called to handle an application

quit event when user did triple shake. Application can shutdown gracefully,

e.g. save state on the flash memory. Application has 1000ms to run handler

and will be termintated after that period. No more handlers will be called.

See also: saveState()

History:

v5.0 - added

Functions

getTime

Syntax:

native getTime();

Description:

Get time in milliseconds since the module start.

Return values:

Time in milliseconds since the module start.

getUserName

Syntax:

native getUserName(userName[], size = sizeof(userName));

Description:

Get the name of a user who is logined on the cube.

Get the user name configured in the WOWCube mobile application to save

results for.

Arguments:

size

size of string to keep a user name

Outputs

userName

string to keep a user name

See also: USER_NAME_LENGTH

quit

Syntax:

native quit();

Description:

Quit from the application.

See also: SENSITIVITY_MENU_CHANGE_SCRIPT

toggleDebugInfo

Syntax:

native toggleDebugInfo();

Description:

Toggle overlay with debug information. TBD - move to GFX

broadcastPacket

Syntax:

native broadcastPacket(type, const data[], size = sizeof(data));

Description:

Broadcast a packet over the cube network.

Arguments:

type

arbitrary packet type

data[]

packet data to broadcast

size

size of the packet data in cells

See also: ON_Packet(), MAX_PACKET_TYPES, MAX_PACKET_SIZE

History:

v6.0 - added

saveState

Syntax:

native bool:saveState(const data[], size = sizeof(data));

Description:

Request to save an application data

Save user settings and/or progress on the flash to restore next time. Each

save data has an incremental ID.

Arguments:

data []

data to save

size

size of data in cells to save

Return values:

True if save was successful.

See also: GAME_SAVE_SIZE, ON_Load(), loadState()

History:

v5.0 - fixed a bug in which only part of a data saved on the flash

loadState

Syntax:

native loadState();

Description:

Request to load an application save data from the flash.

Trigger state load event. It is asynchronous so access to flash memory will

not affect an application performance.

See also: ON_Load(), saveState()

random

Syntax:

native random(min, max);

Description:

Generate random number in half-open range.

Random number generator is initialized before each application start. Seed

for initialization is generated by TRNG (True Random Number Generator).

Arguments:

min

minimal value of range to generate random number

max

maximum value of range to generate random number

Return values:

Pseudo random value from requested range.

History:

v5.0 - fixed a bug in which random does not generate numbers in a given

range.

getAppVersion

Syntax:

native getAppVersion(version[APP_VERSION]);

Description:

Get application version.

WOWCube applications follow semantic versioning scheme (see

https://semver.org). This interface allows to get version parts stored in

the cube application descriptor.

Outputs

• version - structure describing application version

See also: APP_VERSION

History:

v6.0 - added

parseByte

Syntax:

stock parseByte(const arr[], const n)

Description:

Get arbitrary byte value from array.

Pawn works with cells which has a size of 4 bytes. Native interfaces

handling generic data like network messages have size limits for that data.

If application does not need to work with a large numbers, several values

can be packed into a single cell. This function provides interface to

extract such values from array.

Arguments:

arr

array to read byte from

n

number of byte to read

Return values:

Requested byte value.

See also: broadcastPacket(), saveState(), ON_Load(), ON_Packet()

Other

SELF_ID

Syntax:

public const SELF_ID = 0;

Description:

An ID of the module on which application copy is running.