Graphics API

Welcome to the Graphics API tutorial. Here you will learn how to use the Graphics API within SIMCUBE™. Be sure to read the Basics tutorial first. Let's get started!

The first thing to note about the graphics API, is that it is very easy to use. Any .png image up to 64x64 may be loaded by using this command:

IMG = IMG.L IMAGE

IMG is a variable that is assigned the index of the image loaded, this is used with the drawing command to draw the image to the screen. IMG.L is the image loading command. It takes a single value, the name of the .png file located within the IMG folder within the root directory of the application SIMCUBE™.exe. The file name comes after the command with a SPACE separating them.

The Graphics API commands are all double buffered. This is in order to allow animations, and requires that the pixels drawn to the screen are flushed to the visible screen buffer:

VAR = IMG.F

In order to draw a .png image to the off-screen buffer, the following command is used:

VAR = IMG.D IMG XPOS YPOS

VAR is a variable that is assigned 1 if the command succeeds, and 0 if an error occurred. IMG.D is the drawing command to draw an image to an external screen. IMG is the index of the image that was loaded, while XPOS and YPOS are the pixel coordinates to draw the image. The coordinates may be constants or variables.

We are almost done! There are only two commands left to mention. The first one clears the screen, this requires a call to IMG.F to be visible.

VAR = IMG.C

VAR simply checks for error.

The last, but probably not least, is the command to draw a pixel on the screen of any RGB value:

VAR = IMG.P XPOS YPOS R G B

Again VAR will indicate errors. IMG.P is the pixel drawing command. This command takes 5 variables or constants indicating the XPOS and YPOS on the external screen to draw the pixel, as well as the R, G, B value of the color to draw. The R,G,B values may be any number from 0-255.

Conclusion

In conclusion, it is very easy and straight forward to use the Graphics API. Up to 9000, 64x64 images may be loaded total. This number may change in the future. A few things to note about the external screen, is that only one screen per world may be placed. Also, the screen may only be placed on a single chunk. The maximum external screen size is 32x32 cubes (512x512 pixel resolution). Breaking one cube of an external screen array will drop the whole screen as items located at the first screen cube broken. The external screen does not need to be touching a computer to have graphics drawn to it. Only complete rectangles are valid screens, and do not need to be square (widescreen). Images drawn to the screen will remain on the screen until the screen is broken, or an IMG.C command is executed. When placing an external screen array, the first cube placed is ALWAYS considered the top left corner of the screen, and the screen may only be built by placing cubes either on the right side of the screen cube array or under it. Each row of the screen array MUST be completed before placing the next row down, because of this, if a screen array needs to be expanded, the entire screen must be removed and rebuilt.

Also, the game SIMCUBE™ will ALWAYS autosave upon exiting, UNLESS a new game is created and NOT saved. Upon saving a new game, the game will ALWAYS autosave upon exiting.