GUICANVAS is a set of commands for Sauerbraten that allows you to draw pixels in GUI menus using CubeScript.
- Download guicanvas.zip (without extracting it).
- Move the zip to the Sauerbraten home folder (or the main installation folder).
- Find your autoexec.cfg file or create a new one (also in one of the root folders), open it in a text editor and add the following commands:
addzip guicanvas.zip; exec guicanvas.cfg
The zip will be extracted internally and the configuration file (guicanvas.cfg) will be applied whenever you start the game.
Alternatively to step 3 you can type the command /notepad autoexec.cfg during the game to open the built-in text editor.
Currently the installation zip comes with the demos below that you can run and test:
feel free to contribute more :)
Note: Some GUICANVAS demos are expected to replace key binds such as directional arrows.
Behind the scenes GUICANVAS uses .obj mapmodels as screens, each pixel is a mesh whose name corresponds to its position (index) in the 2D plane. The model command to define skins by meshes (in this case objskin) is extremely fast, allowing us to easily update their colors or textures.
For the front end, GUICANVAS uses the guimodelpreview command, which allows us to register and display any mapmodel with a given size and even an animation state.
Another important command is guistrut, with it we can overlay GUI elements and make the magic work.
If you are not into menus or want to create your own physical arcade, you can spawn the screen using the /newent mapmodel $nummapmodels; mmodel guicanvas command in edit mode.
guicanvas.cfg has some commands and variables that you can use.
This is the main command to add a pixel before drawing it, x refers to the horizontal line and y to the vertical, r g b are the colors ranging between 0-1.
If r is set to -1 the pixel will be displayed with complete opacity;
If r is a string it will be treated as a texture path.
This is a helper function that uses guicanvas.setPixels to fill a square with a given size width height at a given x y position.
This is the command to actually draw the screen from the list of added pixels ($guicanvas.pixels), it will also clear the list unless guicanvas.keepPixels is set to 1.
Works as an event hook, the contents of $guicanvas.onupdate are executed every millisecond set by $guicanvas.refreshRate.
This is the main command for creating and displaying the GUI menu, with extra functions to facilitate the positioning of other GUI elements.
action has the same effect as $guicanvas.onupdate, its content is executed every millisecond defined by $guicanvas.refreshRate;
interface is where you can include other GUI elements that you want to see on the screen (guitext, guititle, guibutton...), they are positioned by default at 0 0 unless determined by x and y.
Careful and extensive use of guistrut may be necessary if you wish to hide the original background (the guiskin), which may appear depending on the lenght of your text elements, take a look at the demo files to get an idea of how to correct these.
Alternatively you can always create your own menu using the guimodelpreview command to display the screen.
This command is just a mix of the modelpreviewpitch and modelpreviewfov commands, allows you to control the display of the preview itself in 3D context.
Note: fov can make the preview invisible at certain sizes and values (logically the same applies to pitch :P).
This is the command that determines which screen model will be loaded and displayed, if a certain screen size is not available, the user will be prompted to generate it.
Alternatively you can generate screens with extra customizations using guicanvas.genScreen.
The /guicanvas command displays all .cfg files contained in the "guicanvas" folder and allows you to play or edit them.
