Introduction to Biksel

Biksel is a programming system designed for making pixel art oriented video games and other applications. It is intended to be accessible to beginners with no prior programming experience, and is loosely inspired by the BASIC systems of old. Biksel programs are written in the C programming language, or more specifically a safe subset of C which excludes certain features such as pointers. See C Programming Language — Quick Reference for details.

Please note that Biksel is currently a work in progress: additional features and improvements are planned for the future. For more information or to report a bug see https://fiveysoftware.com/biksel/.

Getting started

In order to write programs with Biksel you need two things:

  1. A working installation of Biksel.
  2. A text editor.

Checking if you have the software installed

To test if you have a working installation of Biksel, enter the following command at the terminal:

bikinfo version

If Biksel is installed, this command will output the version number of your Biksel installation, e.g. 1.0.0. If Biksel is not installed, you will get an error message saying command not found.

If you need to install Biksel, you can obtain a copy from the Biksel website at https://fiveysoftware.com/biksel/.

The recommended editor for writing Biksel programs is a text editor called GNU Emacs. To test if you have GNU Emacs installed, enter the following command at the terminal:

emacs --version

Similarly to before: if Emacs is installed then this command will output a version number; if not you will get an error message.

If you need to install Emacs, the easiest way to do so is usually via your operating system's package manager. For example, on a Debian-based version of GNU/Linux (including the Raspberry Pi's Raspbian operating system) you can install Emacs by entering the following command at the terminal:

sudo apt-get install emacs

Setting up the Emacs text editor

There is one remaining step of preparation: you need to configure the GNU Emacs text editor so that it knows about Biksel. This will make available some useful Biksel-specific shortcut keys within the Emacs editor. If you are new to Emacs, the simplest way to do this configuration step is to enter the following command at the terminal, which will create a configuration file for Emacs in your home directory called .emacs:

**WARNING**: this command will overwrite any existing .emacs file, so if you already have such a file be sure to make a backup of it first.

cp $(bikpath emacs-init-file) ~/.emacs

(Note: the $() syntax in the above command is a feature of the Bash shell language known as command substitution: it passes the output of the bikpath command as the first argument to the cp command; the bikpath command outputs a path to a template Emacs configuration file provided by Biksel; the cp command copies a file; the ~ symbol refers to your home directory.)

For more information about the bikpath command, see Biksel Shell Commands — Quick Reference.

If you are already an Emacs user and have your own .emacs init file, please see the appendix at the end of this introduction instead of using the above command.

Using Biksel

Writing a program

The typical workflow for writing a Biksel program is as follows. Using your preferred file manager, create a new directory for your program and give it a name ending in .bik. For example, hello-world.bik. Next create an empty file inside this directory and give it the name main.c. This file is going to contain the C source code for your program.

Open the GNU Emacs text editor. You can do this either by finding it in your desktop environment's applications menu, or by entering the following command at the terminal:

emacs

To start editing your main.c file in Emacs, drag and drop the file from your file manager into the Emacs text editor window. Then, using Emacs, add some code for your program to main.c. For example, the following minimal program will display the message Hello, world! in a window, wait for the user to press a key, then exit:

void Main(Channel io)
{
  BeginDraw(io);
  BeginDrawText(io, Mono11, White, 10, 230);
  PutText(io, "Hello, world!");
  EndDrawText(io);
  EndDraw(io);

  WaitForKeyPress(io);
}

For more information on using the Emacs text editor see GNU Emacs Text Editor — Quick Reference. For more information on writing Biksel programs see C Programming Language — Quick Reference and Biksel Programming Interface — Quick Reference.

Building and running your program

To build a Biksel program, press F5 within Emacs. This will automatically save any changes that you have made to your program source file. It will also open up a compilation output subwindow in Emacs to tell you whether or not the build has succeeded. If the build has failed (e.g. due to a typo in your program), you will see error messages highlighted in red: you can click on an error message and it will act as a hyperlink to the part of your program that triggered the error.

Once your build has succeeded, press F6 within Emacs to run your program. Note that the compiled executable will have been placed in an automatically-generated subdirectory called build-output within your program's directory.

For convenience it is also possible to build and then immediately run a Biksel program in a single step by pressing F7 within Emacs.

Editing images

To open the Biksel image editor, press F8 within Emacs. For information on using the image editor see Biksel Image Editor — Quick Reference.

When saving an image to disk from the Biksel image editor it is conventional to use a file name ending in .sprite. Such image files have a format called biksel-sprite and may be loaded into Biksel programs using a C procedure called LoadNewSprite. See the section Sprite file of Biksel File Formats — Quick Reference and the section on Sprites of Biksel Programming Interface — Quick Reference for details.

Running the example programs

Biksel comes with several example programs. You can print the path to the directory containing these example programs by entering the following command at the terminal:

bikpath examples

Before running the example programs, it is recommended to make a working copy of them, e.g. in your home directory, so that you can make changes to the copy without losing the originals. For example, enter the following command to make a copy of the Biksel example programs in a new directory called biksel-examples:

cp -r $(bikpath examples) biksel-examples

(Note: the -r argument in the above command indicates a recursive copy, i.e. to copy a directory and all of its contents.)

To run an example program, navigate into its subdirectory within your working copy of the examples. Drag and drop the program's main.c file into Emacs. You can then build and run the program in the usual way as described above in the section on Building and running your program.

Accessing this user manual offline

Copies of this user manual in HTML and PDF formats are included with Biksel. You can print the path to the included manual in your preferred format by entering one of the following commands at the terminal:

bikpath manual-html

or:

bikpath manual-pdf

Alternatively, you can instruct a program of your choice to open the manual directly with one of the following commands:

your-web-browser $(bikpath manual-html)

or:

your-pdf-viewer $(bikpath manual-pdf)

Just replace your-web-browser or your-pdf-viewer with the name of your preferred web browser or PDF viewer program.

Appendix: information for Emacs users

This appendix describes how to configure GNU Emacs to work with Biksel if you are already an Emacs user and have your own .emacs init file.

You will need to add a few lines to your .emacs in order to enable Biksel-specific shortcut keys within Emacs. The relevant lines can be found in the template Emacs init file included with Biksel. Enter the following command at the terminal to open this template init file in Emacs:

emacs $(bikpath emacs-init-file)

The lines you will need are those beneath the heading SECTION 1: BIKSEL. Add them into your own .emacs file, making changes to the key bindings if you wish. (There is no necessity to use anything from the other sections of the template init file, although you may wish to do so if the configuration tweaks there look useful to you.)

For more information about the Biksel-specific part of the template Emacs init file, see Biksel Emacs Lisp Interface — Quick Reference.