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/.
In order to write programs with Biksel you need two things:
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.1.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
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.
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
. For
example, .bik
. Next create an
empty file inside this directory and give it the
name hello-world.bik
. This file is going to contain
the C source code for your program.
main.c
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
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 main.cHello,
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.
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.
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
. Such image files have a format
called .sprite
and may be loaded into
Biksel programs using a C procedure
called biksel-sprite
. See the
section LoadNewSpriteSprite file
of Biksel File
Formats — Quick Reference and the section
on Sprites
of Biksel
Programming Interface — Quick Reference for details.
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
argument in
the above command indicates a -rrecursive
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
file into Emacs. You can
then build and run the program in the usual way as described
above in the section on main.cBuilding and running your program
.
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.
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.