Getting Started

Preface

Traditionally, prgrammer's journey with any new langauge or device or SDK starts with something simple, something like Hello, World application. The history of this dates back to 1978, and seriously, is there a programmer who hasn't got at least one Hello World application witten ever? Doubtful.

So your familiarization with WOWCube SDK starts with a Hello, World (kind of) application too.

But wait a minute.

Before moving to actual coding, let's stop for a second and think of what do we call a computer device ? Most of us would instantly think of a Mac, or PC, or gaming console, or even of mobile phone. We all deal with computer devices daily and we so used to it we almost take for granted that computer has a monitor, it has CPU and memory and storage. Let's try to be a bit more precise: it typically has one CPU, one block of memory and one to three monotors.

Thing is, WOWCube is different.

It is one device, but many. It consists of 8 independent modules each with own CPU and own memory. It has 24 screens that can change relative to each other positions. The modules can talk between each other via internal network.

But hang on you may say, how do I write applications for such challenging environment? This must be too difficult!

Apparently, it is not.

Creation of WOWCube applications is based on several principles and techniques known to any progammer rather well. The SDK provides quite intuitive API for controlling of nearly everything that device can do. So it would not to be that difficult to create your first game for WOWCube.

And to prove the point, let's get started...

Cubeapps and the structure of WOWCube application

First of all, it is important to understand that every WOWCube application constits of eight independent programs, or CUBEAPPS, that run on each device module.

A module is a building block of WOWCube device: it has 3 screens, its own CPU and its own memory. WOWCube devce has 8 modules.

A cubeapp is an application executed on module which implements application logic, rendering, network communication and haptic input

Thus, every WOWCube application is actually a union of eight cubeapps connected via internal network.

During the life of the applicaton, all cubeapps stay in constant interaction. In any random moment of time each cubeapp "knows" position of an own module relatively to the other modules. One module can easily send the data to the others. Finally, when one module receives a haptic command to close an application, all other modules will follow it instantly.

But аll this is provided by the functionality of the CubiOS operating system and done automatically.

The only thing every application must do is to listen to the signals operating system sends.

How?

Via callbacks...

CubiOS callbacks

A callback function is a function passed into a cubeapp application by CubiOS, which is then invoked inside the cubeapp application to complete some kind of routine or action.

A lifecycle of each cubeapp consists of three stages:

• application startup
• execution of application logic
• application shutdown

Of course, the second stage is always divided into multiple smaller stages, such as

• execution of logic
• rendering
• handling of user input
• handling of network communication

CubiOS utilizes callback functions to inform cubeapp application of which stage is running and what is happening.

The following callbacks are supported:

1ON_Init(id, size, const pkt[])
2    Gets called upon successfull load and start of cubeapp application. 
3 
4ON_Tick()
5    Gets called on every tick of cubeapp application internal runloop. In other words, it gets called continuously during the whole lifetime of an application. The frequency of calls depends on multiple factors, such as time of execution of the code within the callback, and not guaranteed to be stable. 
6 
7ON_Render()
8    Application rendering code must be called inside this callback function. It gets called immediately after ONTICK(). Despite that any rendering calls can also be executed from ONTICK() callback, it is not a recommended practice. We advise to separate application logic and rendering into different callbacks. 
9 
10ON_PhysicsTick()
11    Gets called recurrently with not less than 30 milliseconds of delay between the calls. Can be used as a time callback for implementation of in-game physics or visual effects.
12 
13ON_Load(id, size, const pkt[])
14    Gets called upon successful load of in-game data stored in device internal memory.
15 
16ON_Twist(twist[TOPOLOGY_TWIST_INFO])
17    Gets called when device topology - а mutual arrangement of modules relative to each other - is changed. 
18 
19ON_Packet(type, size, const pkt[])
20    Gets called when application receives data from the other module over device internal network.
21 
22ON_Shake(const count) 
23    Gets called when device detects it was shaken.
24 
25ON_Tap(const count, const display, const bool:opposite)
26    Gets called when device registers a tap on one of its screens.
27 
28ON_Quit()
29Gets called to indicate the cubeapp application will be closed.
30 

Simple sequence of callback calls of any cubeapp application looks like this:

1application started
2|
3ON_Init()   <--- initialization code
4|
5- ON_Tick()    <--- application logic
6- ON_Render()  <--- rendering
7  ...
8- ON_Tick()
9- ON_Render()
10  ...
11|
12shake the device
13|
14ON_Quit()   <--- save the data before closing
15|
16application closed
17 

Your first applicaton

Ok, enough of theory, let's get coding!

First of all, create a cubeapp project. We wanted Hello World, right? So let's do it!

In order to create a project, click the CREATE EXAMPLE PROJECT button below, then choose a folder where you would like the project to be created.

You can also navigate through WOWCube SDK examples library using <<PREV and NEXT>> buttons.

Once project is created, you will find the following items in your project's folder:

But before moving to the actual code, let's take a quick peek at what is inside the project file. The project file isn't something you would need to modify often, but to do certain things being familiar with its structure may come in handy.

The project file has the follwing structure:

1{
2"name": "Example1",
3"version": "1.0.0",
4"sdkVersion":"6.1",
5"sourceFile" : "src/main.pwn",
6"scriptFile" : "binary/main.amx",
7"appIcon": {
8  "path": "assets/icon.png"
9},
10"soundAssetsDir":"assets/sounds",
11"imageAssetsDir":"assets/images",
12"appFlags": "0"
13}
14 

It is used to declare three major things: application's name, locations of files and versioning info.

1name:
2    A name of an application as it is shown in the WOWCube's main menu. In other words, it is a label under application's icon
3 
4version:
5    Application version
6 
7sdkVersion:
8    A version of WOWCube SDK used to build the application
9 
10sourceFile:
11    The name and the path to the source 
12 
13scriptFile:
14    The name and the path to the compiled intermediary file that then gets converted into a cubeapp file
15 
16appIcon:
17    The name and the path to the application icon file
18 
19 soundAssetsDir:
20 imageAssetsDir:
21    Paths to image and sound resource folders
22 

So our example's name is Example1, but you can change it by putting a different name and building the cubeapp.

Finally, the source code.

As you can see, the application declares functions for callback handling as we have discussed above. But this is our first cubeapp, and it is very simple: it only implements just one callback - ON_Render().

But how does the cubeapp work exactly?

Let's look at the code of ON_Render callback:

1public ON_Render()
2{
3 
4    //get ready to render on screen 1
5    GFX_setRenderTarget(0);
6 
7    //fill the screen with black color
8    GFX_clear(Colors.black);
9 
10    //render text
11    GFX_drawText([ 120,100 ], TEXT_SIZE, 0, 0, TEXT_ALIGN_CENTER, Colors.white, "HELLO");
12    GFX_drawText([ 120,140 ], TEXT_SIZE, 0, 0, TEXT_ALIGN_CENTER, Colors.white, "WOWCUBE");
13 
14    //render screen buffer
15    GFX_render();
16 
17 
18    //get ready to render on screen 2
19    GFX_setRenderTarget(1);
20 
21    //fill the screen with black color
22    GFX_clear(Colors.black);
23 
24    //render text
25    GFX_drawText([ 120,100 ], TEXT_SIZE, 0, 0, TEXT_ALIGN_CENTER, Colors.white, "HELLO");
26    GFX_drawText([ 120,140 ], TEXT_SIZE, 0, 0, TEXT_ALIGN_CENTER, Colors.white, "WOWCUBE");
27 
28    //render screen buffer
29    GFX_render();
30 
31 
32    //get ready to render on screen 3
33    GFX_setRenderTarget(2);
34 
35    //fill the screen with black color
36    GFX_clear(Colors.black);
37 
38    //render text
39    GFX_drawText([ 120,100 ], TEXT_SIZE, 0, 0, TEXT_ALIGN_CENTER, Colors.white, "HELLO");
40    GFX_drawText([ 120,140 ], TEXT_SIZE, 0, 0, TEXT_ALIGN_CENTER, Colors.white, "WOWCUBE");
41 
42    //render screen buffer
43    GFX_render();
44 
45}
46 

The general principle of drawing on module's screen is simple:

First, you push commands to the graphics pipleine, then you commit them to be rendered on the screen

Since each module has three screens, you would want to do three commits to different screens every time you draw something. But this is not a must, you can actually draw on only one or two screens if you wish.

So, back to the ON_Render code, we take three simple steps for each screen:

• We instruct the application what screen to use for rendering (GFX_setRenderTarget)
• We clear the screen with RGB color (GFX_clear)
• We draw text at screen coordinates (GFX_drawText) and
• We commit this to be drawn on particular screen (GFX_render)

Repeat those three steps for all three screens - and voila, Hello World.

No,

HELLO WOWCUBE