API Reference


Autogenerate TCOD colour definitions by parsing rgb.txt on Xwindows


  • Function PARSE-RGB-FILE (&key (infile *rgb-txt-file*) (outfile *output-file-name*))
    Parse a file of colour definitions in the format of the X-windows file 'rgb.txt'. Generate a file of lisp code that allows the CL-TCOD library to use all the colours defined in the input file, by name.


Common Lisp bindings for libtcod, a truecolour terminal-emulation library written in C.


* Introduction

Welcome to CL-TCOD, an interface between Common Lisp and the Doryen Library,
AKA `libtcod', a portable truecolour console library intended for use with
roguelike games.

CL-TCOD consists of the following files:
1. =tcod.lisp=, a lisp file which creates lisp bindings for C functions in the
   compiled libtcod library, using the =CFFI= lisp foreign function interface.
2. =tcod.asd=, which allows TCOD to be easily loaded and used as a library by
   other common lisp programs, via the =ASDF= library-loading facility.
3. =tcod-colours.lisp=, a lisp file containing definitions for all the colours
   named in /etc/X11/rgb.txt; autogenerated using 'parse-rgb' (see below)
4. =parse-rgb.lisp=, a lisp file containing code for parsing =/etc/X11/rgb.txt=
   and generating tcod-colours.lisp
5. =parse-rgb.asd=, ASDF system definition file for =parse-rgb.lisp=

CL-TCOD has been tested with SBCL 1.0.36 on Linux and Windows, Clozure 1.5
on Linux and Windows, and CLISP on Windows.

**Note** that it has not been used on a Mac; if you do this you may need to
tell CFFI the name of the compiled libtcod library under MacOS. To do this,
open =tcod.lisp= in an editor, find the ='(define-foreign-library...'= clause,
uncomment the ='(:macintosh...)'= line and change the string on that line to
the name of the libtcod library file.

* License

The CL-TCOD package is placed in the Public Domain by its author.

* Dependencies

=CL-TCOD= depends on the following libraries:
1. ASDF: [[]]
2. DEFSTAR: [[]]
3. CFFI: [[]]

* Hints on installation

You need to know your way around your chosen common lisp and how to install and
load lisp libraries before proceeding. You also need to have a version of
libtcod newer than 1.4.1rc2, which is the first version that includes the
='wrappers.c'= and ='wrappers.h'= source files that allow CL-TCOD to interface
with libtcod.

1. Ensure you have a working common lisp installation.
2. Ensure either [[][Quicklisp]] (recommended) or the
   ASDF lisp library is installed.
3. If CFFI or DEFSTAR are not installed, download and install them somewhere
   ASDF can find them. CFFI requires several third-party lisp libraries -- see
   the CFFI documentation for more details.  Note that if you have
   Quicklisp installed, you can install CFFI and its dependencies
   easily using the command =(ql:quickload "cffi")= at the Lisp prompt.
4. Put the CL-TCOD files in a directory where ASDF can find them.
5. Make sure libtcod is installed and compiled. Make sure the libtcod and libSDL
   dynamically linked libraries (=.DLL= or =.SO= files) are somewhere your lisp
   system can find them. They probably are, but if CFFI complains about being unable
   to find the libraries, you can either copy them to an appropriate directory or
   add their directory to the list variable =cffi:*foreign-library-directories*=
   e.g. by typing the following in the lisp interpreter:

;;;   (push #P"/my/libtcod/directory/" cffi:*foreign-library-directories*)

   *On windows*, DLL files should be put in one of the directories listed in the
   =PATH= environment variable. You will need to put =SDL.dll= in the same place
   if you don't already have SDL installed.

   *On Linux*, you can usually put .SO files in =/usr/local/lib/=.
   Use your package installer to install =libSDL=.
   Try running the libtcod demo programs to check everything works.

6. Start lisp, then load CL-TCOD. Using Quicklisp (recommended):

;;;   (ql:quickload :tcod)

   Using ASDF:

;;;   (load "/path/to/asdf/asdf.lisp")
;;;   (asdf:oos 'asdf:load-op :tcod)

7. Type something like the following commands at the lisp prompt to start using
   TCOD from within Lisp. Alternatively you can type =(tcod:hello-world)=, which
   is a function containing the code below.

;;;   (tcod:console-set-custom-font "terminal.png" '(:font-layout-ascii-in-row) 16 16)
;;;   (tcod:console-init-root 80 25 :title "Test")
;;;   (tcod:console-clear tcod:*root*)
;;;   (tcod:console-print tcod:*root* 1 1 "Hello, world!~%")
;;;   (tcod:console-wait-for-keypress t)

* Differences between CL-TCOD and libtcod

** Naming conventions

The C function =TCOD_foobar= corresponds to the lisp function =foobar=, which
is in the =tcod= package (and so requires a prefix of =tcod:= to access in most
situations). Underscores become hyphens. So:

:  TCOD_foobar_function(a, b)     <===>    (tcod:foobar-function a b)

`Predicate functions' are functions whose main job is to return a boolean
value, true (non =NIL=) or false (=NIL=), that answers a question. These have a
terminal '?' added to their name:

:  TCOD_console_is_fullscreen()   <===>    (tcod:console-is-fullscreen?)

C enums have generally more succinct names. As they are lisp keywords, their
names all begin with =':'=. THey are named according to the following pattern:

:  TCODK_BACKSPACE (etc)         <===>  :backspace
:  TCOD_CHAR_HLINE  (etc)        <===>  :char-hline
:  TCOD_COLCTRL_1  (etc)         <===>  :colctrl-1
:  TCOD_BKGND_SET (etc)          <===>  :set
:  TCOD_FONT_LAYOUT_ASCII_INCOL  <===>  :font-layout-ascii-in-col
:  FOV_SHADOW                    <===>  :fov-shadow
:  TCOD_KEY_PRESSED              <===>  :key-pressed
:  CENTER                        <===>  :center

In general, most functions exist in both U.S. and non-U.S. spellings, This is
mainly relevant to those functions with colour/color or centre/center in their

** Colournums

In libtcod, colours are represented as structures containing three integer
values: *red*, *green* and *blue* (each 0-255). The name of the structure type is

In CL-TCOD, these colour structs are converted into 3-byte integers using the C
functions =int_to_color(int)= and =color_to_int(TCOD_color_t)=, both defined in
=wrappers.c=. The 3 bytes are red, green and blue in order (blue is 1's). ie:

:    /* C */                              ;; lisp ;;
:   struct TCOD_color_t {r, g, b}  <==>   #x00RRGGBB

So, for example, one way to use the function =TCOD_color_multiply_scalar= from
lisp is:

;;;  (tcod:color-multiply-scalar (tcod:compose-colour 218 165 32) 0.5)

All C functions that take or return =TCOD_color_t= structs, are wrapped by lisp
functions that take or return integers as described above.

** Colours by keyword

A lisp keyword is any symbol beginning with ':'. In lisp, keywords (like all
symbols) are first-class values and can be passed around just like any other
value. CL-TCOD uses keywords to refer to particular colours, for example the
keyword =:cyan= refers to the colour #x0056A3CD (or 5678029 in decimal notation).

You can use keywords instead of colournums as arguments to lisp functions, by
using the function =colour= to return the colournum associated with a keyword:

;;;  (tcod:colour :cyan)    ; returns 5678029

You can also define your own colour names, like so:

;;;  (tcod:make-colour :my-goldenrod 218 165 32)
;;;  (tcod:color-multiply-scalar (tcod:colour :my-goldenrod) 0.5)

CL-TCOD knows all the colour names defined in the 'rgb.txt' file under
Xwindows, eg =:navajo-white, :honeydew, :mint-cream=, and so on. There is
nothing special about the fact that rgb.txt comes from Xwindows -- the colours
are just named R,G,B values and can be used anywhere that CL-TCOD can be
used. Look in the source file ='tcod-colours.lisp'= to see the available colour
names. If you are using [[][GNU Emacs]], the
king of lisp IDEs, do =M-x list-colors-display= to see a list of all colours.

** Lisp =format= versus C =printf=

The TCOD functions that accept =printf=-like string-formatting arguments,
have been modified to instead accept arguments to Common Lisp's =format=
function.'  For example:

  TCOD_console_print (con, x, y, "Printing at %d, %dn", x, y);


;;;    (tcod:console-print con x y "Printing at ~D, ~D~%" x y)

** Miscellaneous extra functions

- [[console-print-double-frame]] is like [[console-print-frame]], but
  but draws using `double-line' characters:

;;;  (tcod:console-print-double-frame CONSOLE X Y W H EMPTY? STRING...)

** Coverage

Does not provide wrappers for:
- File parser. Using this from lisp would be a very cumbersome way to read
  values from a file, as the resulting values are not lisp objects. You would
  be better to either consider using the lisp
  `read' function, or looking into lisp libraries for parser generation.
- =namegen-get-sets= -- I haven't yet implemented this as it will have to
  involve converting from libtcod's bespoke 'linked list' to a lisp list.
  You may be better to write your random name generator in lisp (fairly trivial).
- =sys-get-directory-content=, =sys-file-exists=, =sys-is-directory=,
  =sys-delete-file=: Common Lisp already has functions that do the same thing.

* Resources

** Specific to CL-TCOD and libtcod

The latest version of CL-TCOD is available at:


Forum for discussion of CL-TCOD and use of lisp in roguelike games:

    [[][Roguecentral Lisp forum]]

The latest version of libtcod is available at:


This Common Lisp package depends on CFFI, the Common Foreign Function Interface:


** Learning Common Lisp

Recently written book, 'Practical Common Lisp'. buy hard copy or download free.
Recommended, especially if coming from non-lisp languages.

- [[]]

[[][Quicklisp]] allows you to very easily install
libraries -- it automatically downloads and installs a library and its
dependencies, from within Lisp.  If you don't decide to go with Lisp in a
Box (below), then Quicklisp should be the first thing you install once you have
your lisp running.

*"Lisp in a Box"* -- aims to make it easy to start using Common Lisp by
providing a single download with everything set up in advance (Lisp, Emacs,
SLIME, and Quicklisp).

- [[]]

Lisp editors and IDEs:
- [[][GNU Emacs]] (the best; see below)
  - [[][SLIME]] is the Emacs interface to
    Common Lisp.
- [[][Cusp]], a common lisp plugin for Eclipse.
- The [[][Allegro]] and
  [[][LispWorks]] lisp implementations each have a
  builtin IDE.
- If you are on a Mac, the free, high-quality [[][Clozure CL]]
  has a builtin graphical IDE.
- Some editors with good lisp syntax highlighting include jEdit and Notepad++.

** A note on editors and IDEs

Emacs is a very powerful program. It is mainly used as a programmers' text and
source code editor, but it can do -- and plugins exist to make it do -- just
about anything you can imagine. It is mostly written in a dialect of lisp, and
this is also its extension language. When combined with SLIME, a plugin
that allows it to communicate directly with a running common lisp
compiler/interpreter, Emacs is not only the best IDE for common lisp, but
one of the best and most advanced IDEs available for any programming language.

The downside: because Emacs + SLIME is so good, common lisp programmers have
put very little effort into getting other popular programming editors/IDEs to
support common lisp, at least beyond simple syntax highlighting. Emacs is an
idiosyncratic program (though development is active, it is about 34 years old)
and despite good efforts to modernise/regularise its interface it still has a
steeper learning curve than many other IDEs, especially when you are also
struggling to set up SLIME and get it to communicate through a socket with
your lisp process...

My advice is that while all roads lead to Emacs, you don't have to hurry to get
there. Initially you should concentrate on getting common lisp set up and
starting to learn the language. Think about using the trial version of one of
the big commercial implementations (Allegro or LispWorks), as they have
built-in IDEs. Once you are ready to move on from them, install Emacs and

** Commercial Common Lisp implementations

These are both high quality, but painfully expensive. Luckily they have
'trial' versions that can be downloaded for free, and which I recommend you
use when beginning to learn Common Lisp as they come with integrated
graphical editors/development environments (although if you have a Mac
you may wish to investigate Clozure CL's IDE -- see below).

- [[][Allegro]] -- starts at $599 USD
- [[][LispWorks]] -- starts at $900 USD for a
  noncommercial license. The trial version quits automatically after 5 hours.

** Full-featured, free Common Lisp implementations

Move on to one of these if and when you outgrow Allegro or LispWorks.

For the title of the best, most robust free multiplatform Common Lisp compiler,
it is currently a very close call between these two:
- [[][Steel Bank Common Lisp (SBCL)]] Compiles to
  machine code, great on Linux/Mac,
  still nominally 'experimental' on Windows but actually seems very stable
  on that platform.
- [[][Clozure CL]] Compiles to machine code; native to
  Mac but recently ported to Linux and Windows. Formerly known as OpenMCL.
  The Mac version has a graphical IDE.
  Not to be confused with [[][Clojure]], which is a different
  dialect of lisp from Common Lisp.

Other worthwhile free implementations:
- [[][GNU CLISP]] Bytecode compiler, so programs won't run
  as fast as in the compiled lisps discussed above. However it runs pretty much
  everywhere, and is easy to install on Windows.
- [[][Embeddable Common Lisp]] Promising, compiles
  to C and then passes code to your C compiler. Does this 'on the fly' when
  running as an interpreter. Also designed to be easily embeddable in non-Lisp
  applications as a scripting language.
- [[][Armed Bear Common Lisp]]
  Common Lisp compiler running inside the Java virtual machine, so your
  code will run on any platform and can use all the Java libraries. I doubt
  you'll be able to use libtcod with this though.

Help & advice with lisp:

  • Cffi-Function SDL-GET-MOUSE-STATE
  • Function SDL-GET-MOUSE-STATE (xptr yptr)
  • Cffi-Enum KEYCODE
  • Type KEYCODE
  • Cffi-Struct KEY-PRESS
  • Struct KEY
    The structure used by CL-TCOD to represent key-press events. Corresponds to the structure used by libtcod.
  • Function KEY-P (object)
  • Function KEY-VK (instance)
  • Function (setf KEY-VK) (value instance)
  • Function KEY-C (instance)
  • Function (setf KEY-C) (value instance)
  • Function KEY-PRESSED (instance)
  • Function (setf KEY-PRESSED) (value instance)
  • Function KEY-LALT (instance)
  • Function (setf KEY-LALT) (value instance)
  • Function KEY-LCTRL (instance)
  • Function (setf KEY-LCTRL) (value instance)
  • Function KEY-RALT (instance)
  • Function (setf KEY-RALT) (value instance)
  • Function KEY-RCTRL (instance)
  • Function (setf KEY-RCTRL) (value instance)
  • Function KEY-SHIFT (instance)
  • Function (setf KEY-SHIFT) (value instance)
  • Function MAKE-KEY (&key ((vk vk) :none) ((c c) #\nul) ((pressed pressed) nil) ((lalt lalt) nil) ((lctrl lctrl) nil) ((ralt ralt) nil) ((rctrl rctrl) nil) ((shift shift) nil))
  • Cffi-Enum COLCTRL
  • Type COLCTRL
  • Cffi-Bitfield KEY-STATE
  • Type KEY-STATE
  • Cffi-Type CONSOLE
  • Type CONSOLE
  • Cffi-Type ZIPPTR
  • Type ZIPPTR
  • Cffi-Struct MOUSE-STATE
  • Struct MOUSE
    Structure used by CL-TCOD to represent mouse status.
  • Function MOUSE-X (instance)
  • Function (setf MOUSE-X) (value instance)
  • Function MOUSE-Y (instance)
  • Function (setf MOUSE-Y) (value instance)
  • Function MOUSE-DX (instance)
  • Function (setf MOUSE-DX) (value instance)
  • Function MOUSE-DY (instance)
  • Function (setf MOUSE-DY) (value instance)
  • Function MOUSE-CX (instance)
  • Function (setf MOUSE-CX) (value instance)
  • Function MOUSE-CY (instance)
  • Function (setf MOUSE-CY) (value instance)
  • Function MOUSE-LBUTTON (instance)
  • Function (setf MOUSE-LBUTTON) (value instance)
  • Function MOUSE-RBUTTON (instance)
  • Function (setf MOUSE-RBUTTON) (value instance)
  • Function MOUSE-MBUTTON (instance)
  • Function (setf MOUSE-MBUTTON) (value instance)
  • Function MOUSE-LBUTTON-PRESSED (instance)
  • Function (setf MOUSE-LBUTTON-PRESSED) (value instance)
  • Function MOUSE-RBUTTON-PRESSED (instance)
  • Function (setf MOUSE-RBUTTON-PRESSED) (value instance)
  • Function MOUSE-MBUTTON-PRESSED (instance)
  • Function (setf MOUSE-MBUTTON-PRESSED) (value instance)
  • Function MOUSE-WHEEL-UP (instance)
  • Function (setf MOUSE-WHEEL-UP) (value instance)
  • Function MOUSE-WHEEL-DOWN (instance)
  • Function (setf MOUSE-WHEEL-DOWN) (value instance)
  • Function MAKE-MOUSE (&key ((x x) 0) ((y y) 0) ((dx dx) 0) ((dy dy) 0) ((cx cx) 0) ((cy cy) 0) ((dcx dcx) 0) ((dcy dcy) 0) ((lbutton lbutton) nil) ((rbutton rbutton) nil) ((mbutton mbutton) nil) ((lbutton-pressed lbutton-pressed) nil) ((rbutton-pressed rbutton-pressed) nil) ((mbutton-pressed mbutton-pressed) nil) ((wheel-up wheel-up) nil) ((wheel-down wheel-down) nil))
  • Cffi-Type MAPPTR
  • Type MAPPTR
  • Cffi-Type A*-PATH
  • Type A*-PATH
  • Variable *ROOT*
    The root console.
  • Variable +NULL+
    The null pointer.
  • Function MAKE-SIMPLE-KEY (ch)
  • Function SAME-KEYS? (key1 key2)
  • Function COMPOSE-COLOUR (r g b)
    Given three integer values R, G and B, representing the red, green and blue components of a colour, return a 3 byte integer whose value is #xBBGGRR.
  • Function COMPOSE-COLOR (r g b)
  • Function COLOUR-RGB (r g b)
  • Function COLOR-RGB (r g b)
  • Function COLOUR-HSV (hue sat val)
    Return a new colour with the given HSV (hue, saturation and value) components.
  • Function COLOR-HSV (hue sat val)
  • Function DECOMPOSE-COLOUR (num)
    Given a colournum #xBBGGRR, return R, G and B integer values as 3 separate return values.
  • Function DECOMPOSE-COLOR (num)
  • Function INVERT-COLOUR (num)
  • Function INVERT-COLOR (num)
  • Function BACKGROUND-ALPHA (alpha)
  • Function BACKGROUND-ADD-ALPHA (alpha)
  • Function START-COLOURS
  • Function START-COLORS
  • Function MAKE-COLOUR (kwd r g b)
  • Function MAKE-COLOR (kwd r g b)
  • Function COLOUR->GRAYSCALE (col)
  • Function COLOR->GRAYSCALE (col)
  • Function COLOUR (keywd &optional (error? nil))
    Given a colour keyword such as :GREY, return its corresponding RGB value (#xRRGGBB). If the keyword is unrecognised, then either return a light grey colour, or raise an error (if `error?' is non-nil).
  • Function COLOR (keywd)
  • Function COLOUR->KEYWORD (colournum)
  • Function COLOR->KEYWORD (colournum)
  • Function COLCTRL->CHAR (ctrl)
  • Function COLOUR-EQUALS? (c1 c2)
  • Function COLOR-EQUALS? (c1 c2)
  • Function COLOUR-ADD (c1 c2)
  • Function COLOR-ADD (c1 c2)
  • Function COLOUR-SUBTRACT (c1 c2)
  • Function COLOR-SUBTRACT (c1 c2)
  • Function COLOUR-MULTIPLY (c1 c2)
  • Function COLOR-MULTIPLY (c1 c2)
  • Function COLOUR-MULTIPLY-SCALAR (c1 value)
  • Function COLOR-MULTIPLY-SCALAR (c1 value)
  • Function COLOUR-LERP (c1 c2 coef)
  • Function COLOR-LERP (c1 c2 coef)
  • Function COLOUR-SET-HSV (con hue sat v)
  • Function COLOR-SET-HSV (con hue sat v)
  • Function COLOUR-GET-HUE (c)
  • Function COLOUR-GET-VALUE (c)
  • Function COLOUR-GET-HSV (c)
  • Function COLOUR-SET-HUE (colour hue)
    Return COLOUR with its hue modified to HUE.
  • Function COLOUR-SET-SATURATION (colour sat)
    Return COLOUR with its saturation modified to SAT.
  • Function COLOUR-SET-VALUE (colour val)
    Return COLOUR with its HSV value modified to VAL.
  • Function COLOUR-SHIFT-HUE (colour hshift)
  • Function COLOR-GET-HSV (colour)
  • Function COLOR-GET-HUE (colour)
  • Function COLOR-GET-SATURATION (colour)
  • Function COLOR-GET-VALUE (colour)
  • Function COLOR-SET-HUE (colour hue)
  • Function COLOR-SET-SATURATION (colour sat)
  • Function COLOR-SET-VALUE (colour val)
  • Function COLOR-SHIFT-HUE (colour hshift)
    Are the relative coordinates X,Y within the bounds of console CON?
  • Function CONSOLE-INIT-ROOT (width height &key (title "libtcod") (fullscreen? nil) (renderer :renderer-glsl))
  • Function CONSOLE-SET-CUSTOM-FONT (fontfile flags &optional (chars-horizontal 0) (chars-vertical 0))
  • Function CONSOLE-MAP-ASCII-CODE-TO-FONT (asciicode fontchar-x fontchar-y)
  • Function CONSOLE-MAP-ASCII-CODES-TO-FONT (asciicode num-codes fontchar-x fontchar-y)
  • Function CONSOLE-MAP-STRING-TO-FONT (str fontchar-x fontchar-y)
  • Function CONSOLE-SET-WINDOW-TITLE (title)
  • Function CONSOLE-SET-FULLSCREEN (full?)
  • Function CONSOLE-CLEAR (con)
  • Function CONSOLE-SET-DIRTY (rootx rooty width height)
    Declares an area of the =*root*= console to be 'dirty'.
  • Function CONSOLE-GET-CHAR-BACKGROUND (con x y)
  • Function CONSOLE-GET-CHAR-FOREGROUND (con x y)
  • Function CONSOLE-SET-CHAR-BACKGROUND (con x y col flag)
  • Function CONSOLE-SET-CHAR-FOREGROUND (con x y col)
  • Function CONSOLE-SET-CHAR (con x y ch)
  • Function CONSOLE-FILL-CHAR (con ch fx fy fw fh)
    Fill a rectangular area with the character CH.
  • Function CONSOLE-PUT-CHAR (con x y ch flag)
  • Function CONSOLE-PUT-CHAR-EX (con x y ch fg bg)
  • Function CONSOLE-SET-BACKGROUND-FLAG (con flag)
  • Function CONSOLE-SET-ALIGNMENT (con align)
  • Function CONSOLE-GET-ALIGNMENT (con)
  • Function CONSOLE-PRINT (con x y fmt &rest args)
  • Function CONSOLE-PRINT-EX (con x y flag align fmt &rest args)
  • Function CONSOLE-PRINT-RECT (con x y w h fmt &rest args)
  • Function CONSOLE-PRINT-RECT-EX (con x y w h flag align fmt &rest args)
  • Function CONSOLE-RECT (con x y width height clear? flag)
  • Function CONSOLE-GET-HEIGHT-RECT (con x y w h fmt &rest args)
  • Function CONSOLE-HLINE (con x y len flag)
  • Function CONSOLE-VLINE (con x y len flag)
  • Function CONSOLE-PRINT-FRAME (con x y width height empty? flag fmt &rest args)
  • Function CONSOLE-PRINT-DOUBLE-FRAME (con x y width height empty? flag fmt &rest args)
  • Function CONSOLE-GET-CHAR (con x y)
  • Function CONSOLE-SET-FADE (val fade)
  • Function CONSOLE-FLUSH
  • Function CONSOLE-SET-COLOUR-CONTROL (control-num fore back)
  • Function CONSOLE-SET-COLOR-CONTROL (control-num fore back)
  • Function CONSOLE-NEW (width height)
  • Function CONSOLE-GET-WIDTH (con)
  • Function CONSOLE-GET-HEIGHT (con)
  • Function CONSOLE-BLIT (src xsrc ysrc wsrc hsrc dest xdest ydest foreground-alpha background-alpha)
  • Function CONSOLE-DELETE (con)
  • Function CONSOLE-MAP-STRING-TO-FONT-UTF (str fontchar-x fontchar-y)
  • Function CONSOLE-PRINT-UTF (con x y fmt &rest args)
  • Function CONSOLE-PRINT-EX-UTF (con x y flag align fmt &rest args)
  • Function CONSOLE-PRINT-RECT-UTF (con x y w h fmt &rest args)
  • Function CONSOLE-PRINT-RECT-EX-UTF (con x y w h flag align fmt &rest args)
  • Function CONSOLE-WAIT-FOR-KEYPRESS (flush?)
  • Function CONSOLE-SET-KEYBOARD-REPEAT (initial-delay interval)
  • Function IS-KEY-PRESSED? (code)
  • Function NAMEGEN-PARSE (filename rng)
  • Function NAMEGEN-GENERATE (name allocate?)
  • Function NAMEGEN-GENERATE-CUSTOM (name rule allocate?)
  • Function ZIP-NEW
  • Function ZIP-DELETE (zip)
  • Function ZIP-PUT-CHAR (zip ch)
  • Function ZIP-PUT-INT (zip val)
  • Function ZIP-PUT-FLOAT (zip val)
  • Function ZIP-PUT-STRING (zip val)
  • Function ZIP-PUT-DATA (zip nbytes data)
  • Function ZIP-PUT-IMAGE (zip image)
  • Function ZIP-PUT-CONSOLE (zip con)
  • Function ZIP-PUT (zip val)
  • Function ZIP-PUT-COLOUR (zip colour)
  • Function ZIP-PUT-COLOR (zip color)
  • Function ZIP-SAVE-TO-FILE (zip filename)
  • Function ZIP-LOAD-FROM-FILE (zip filename)
  • Function ZIP-GET-CHAR (zip)
  • Function ZIP-GET-INT (zip)
  • Function ZIP-GET-FLOAT (zip)
  • Function ZIP-GET-STRING (zip)
  • Function ZIP-GET-DATA (zip nbytes data)
  • Function ZIP-GET-IMAGE (zip)
  • Function ZIP-GET-CONSOLE (zip)
  • Function ZIP-GET-CURRENT-BYTES (zip)
  • Function ZIP-GET-REMAINING-BYTES (zip)
  • Function ZIP-SKIP-BYTES (zip nbytes)
  • Function ZIP-GET-COLOUR (zip)
  • Function ZIP-GET-COLOR (zip)
  • Function SYS-WAIT-FOR-EVENT (eventmask key mouseptr flush?)
  • Function SYS-CHECK-FOR-EVENT (eventmask key mouseptr)
  • Function SYS-GET-EVENTS
    User-friendly wrapper for the new input event model in libtcod 1.5.1rc1. When called, returns a list of all queued events (calling the function also EMPTIES the queue). Each element in the list is a cons cell of the form (EVENT-TYPE . DATA) where EVENT-TYPE is a member of the `event' enum, and DATA is either a key struct or a mouse-state struct.
  • Function SYS-CREATE-DIRECTORY (path)
  • Function SYS-DELETE-DIRECTORY (path)
  • Function SYS-SLEEP-MILLI (val)
  • Function SYS-SAVE-SCREENSHOT (&optional (filename (null-pointer)))
  • Function SYS-SET-FPS (val)
  • Function SYS-GET-FPS
  • Function SYS-REGISTER-SDL-RENDERER (callback)
  • Function SYS-FORCE-FULLSCREEN-RESOLUTION (width height)
    Return the currently active renderer.
  • Function SYS-SET-RENDERER (renderer)
    Change the currently active renderer.
  • Function SYS-GET-CHAR-SIZE
    Return the dimensions of each character in the current font bitmap.
  • Function SYS-CLIPBOARD-SET (text)
  • Function SYS-UPDATE-CHAR (ascii fontx fonty image x y)
  • Function RANDOM-NEW (algorithm)
  • Function RANDOM-NEW-FROM-SEED (algorithm seed)
  • Function RANDOM-DELETE (rng)
  • Function RANDOM-SAVE (rng)
  • Function RANDOM-RESTORE (rng backup)
  • Function RANDOM-SET-DISTRIBUTION (rng dist)
  • Function RANDOM-GET-INT (rng min max)
  • Function RANDOM-GET-FLOAT (rng min max)
  • Function RANDOM-GET-DOUBLE (rng min max)
  • Function RANDOM-GET-INT-MEAN (rng min max mean)
  • Function RANDOM-GET-FLOAT-MEAN (rng min max mean)
  • Function RANDOM-GET-DOUBLE-MEAN (rng min max mean)
  • Function MOUSE-GET-STATUS (&optional (update? nil))
    Note that as of libtcod 1.5.1rc1, `mouse-get-status' returns information about the status of the mouse as at the last time `sys-check-for-event' was called. If you want the *current* status of the mouse to be returned instead, UPDATE? should be non-nil.
  • Function MOUSE-SHOW-CURSOR (visible?)
  • Function MOUSE-MOVE (pixel-x pixel-y)
  • Function IMAGE-NEW (width height)
    Return a new image, filled with black.
  • Function IMAGE-REFRESH-CONSOLE (image con)
  • Function IMAGE-DELETE (image)
  • Function IMAGE-FROM-CONSOLE (con)
    Return a new image whose contents are a 'screenshot' of the console =CON=.
  • Function IMAGE-LOAD (filename)
    Read an image from a file and return it.
  • Function IMAGE-INVERT (image)
  • Function IMAGE-HFLIP (image)
  • Function IMAGE-VFLIP (image)
  • Function IMAGE-ROTATE90 (image num-rotations)
  • Function IMAGE-SCALE (image new-width new-height)
  • Function IMAGE-CLEAR (image colour)
    Fill the image =IMAGE= with the colour =COLOUR=.
  • Function IMAGE-SAVE (image filename)
    Write the image =IMAGE= to a file. The filename must end in =.BMP= or =.PNG=.
  • Function IMAGE-GET-PIXEL (image pixel-x pixel-y)
    Return the colour of the pixel at =(PIXEL-X, PIXEL-Y)= in =IMAGE=.
  • Function IMAGE-GET-MIPMAP-PIXEL (image x0 y0 x1 y1)
    Calculate the interpolated colour of the pixel at =(PIXEL-X, PIXEL-Y)= in =IMAGE=.
  • Function IMAGE-PUT-PIXEL (image pixel-x pixel-y colour)
    Set the colour of the pixel at =(PIXEL-X, PIXEL-Y)= in =IMAGE= to =COLOUR=.
  • Function IMAGE-BLIT (image con x y flag scalex scaley angle)
  • Function IMAGE-BLIT-RECT (image con x y width height flag)
  • Function IMAGE-BLIT-2X (image dest dx dy sx sy width height)
  • Function IMAGE-SET-KEY-COLOR (image key-color)
  • Function IMAGE-SET-KEY-COLOUR (image key-colour)
  • Function IMAGE-GET-WIDTH (image)
  • Function IMAGE-GET-HEIGHT (image)
  • Function IMAGE-GET-ALPHA (image x y)
  • Function IMAGE-IS-PIXEL-TRANSPARENT? (image x y)
  • Function NOISE-NEW (dimensions &key (hurst +noise-default-hurst+) (lacunarity +noise-default-lacunarity+) (rng +null+))
    Return a new noise object with the given characteristics.
  • Function NOISE-DELETE (noise)
    Destroy a noise object.
  • Function NOISE-SET-TYPE (noise noise-type)
    Set the type of noise produced by a noise object.
  • Function NOISE-GET (noise &rest nums)
    Returns the flat noise function at the given coordinates.
  • Function NOISE-GET-EX (noise noise-type &rest nums)
    Returns the flat noise function at the given coordinates, using noise type NOISE-TYPE.
  • Function NOISE-GET-FBM (noise octaves &rest nums)
    Returns the fractional Brownian motion function at the given coordinates.
  • Function NOISE-GET-FBM-EX (noise noise-type octaves &rest nums)
    Returns the fractional Brownian motion function at the given coordinates, using noise type NOISE-TYPE.
  • Function NOISE-GET-TURBULENCE (noise octaves &rest nums)
    Returns the turbulence function at the given coordinates.
  • Function NOISE-GET-TURBULENCE-EX (noise noise-type octaves &rest nums)
    Returns the turbulence function at the given coordinates, using noise type NOISE-TYPE.
  • Function HEIGHTMAP-NEW (width height)
    Return a new heightmap with the given dimensions.
  • Function HEIGHTMAP-GET-VALUE (heightmap x y)
    Return the height at position =(X, Y)= in the heightmap.
  • Function HEIGHTMAP-GET-INTERPOLATED-VALUE (heightmap x y)
    Calculate the height at position =(X, Y)= in the heightmap, where the coordinates might not be integers.
  • Function HEIGHTMAP-GET-SLOPE (heightmap x y)
    Return the slope at position =(X, Y)= in the heightmap. The value returned will be between 0 and pi/2.
  • Function HEIGHTMAP-SET-VALUE (heightmap x y value)
    Set the height at position =(X, Y)= in the heightmap to =VALUE=.
  • Function HEIGHTMAP-ADD (heightmap value)
    Add =VALUE= to all heights in the heightmap.
  • Function HEIGHTMAP-ADD-FBM (heightmap noise mulx muly addx addy octaves delta scale)
    Add values from the random noise object =NOISE= to all heights in equivalent positions in =HEIGHTMAP=.
  • Function HEIGHTMAP-SCALE (heightmap factor)
    Multiply all the heights in the heightmap by =SCALE=.
  • Function HEIGHTMAP-LERP-HM (hm1 hm2 result coef)
    Fill the heightmap =RESULT= with the results of a lerp operation between the two heightmaps =HM1= and =HM2=.
  • Function HEIGHTMAP-ADD-HM (hm1 hm2 result)
    Add the heights in =HM1= to heights in equivalent positions in =HM2=, and store the results in the heightmap =RESULT=.
  • Function HEIGHTMAP-MULTIPLY-HM (hm1 hm2 result)
    Multiply the heights in =HM1= by the heights in equivalent positions in =HM2=, and store the results in the heightmap =RESULT=.
  • Function HEIGHTMAP-CLEAR (heightmap)
    Set all the heights in the heightmap to zero.
  • Function HEIGHTMAP-DELETE (heightmap)
    Destroy the heightmap object =HEIGHTMAP=.
  • Function HEIGHTMAP-CLAMP (heightmap min max)
    If any height in =HEIGHTMAP= is below =MIN= or above =MAX=, set it equal to =MIN= or =MAX= respectively.
  • Function HEIGHTMAP-COUNT-CELLS (heightmap min max)
    Return the number of cells in =HEIGHTMAP= which contain heights between =MIN= and =MAX=.
  • Function HEIGHTMAP-HAS-LAND-ON-BORDER? (heightmap waterlevel)
    Return true if any of the border cells of =HEIGHTMAP= have heights greater than =WATERLEVEL=.
  • Function HEIGHTMAP-GET-MIN (heightmap)
    Return the lowest height in =HEIGHTMAP=.
  • Function HEIGHTMAP-GET-MAX (heightmap)
    Return the highest height in =HEIGHTMAP=.
  • Function HEIGHTMAP-NORMALIZE (heightmap min max)
    Scale all the heights in =HEIGHTMAP= so that the lowest is equal to =MIN= and the highest is equal to =MAX=.
  • Function HEIGHTMAP-NORMALISE (heightmap min max)
  • Function HEIGHTMAP-COPY (source dest)
    Copy the heightmap =SOURCE= into the heightmap object =DEST=.
  • Function HEIGHTMAP-RAIN-EROSION (heightmap num-drops erosion-coef sedimentation-coef &optional (rng +null+))
    'Erode' the heightmap =HEIGHTMAP= by dropping =NUM-DROPS= 'raindrops' in random locations.
  • Function HEIGHTMAP-DIG-BEZIER (heightmap coords start-radius start-depth end-radius end-depth)
    Carve a path through =HEIGHTMAP= using a cubic Bezier curve.
  • Function HEIGHTMAP-DIG-LINE (heightmap x1 y1 x2 y2 radius depth)
  • Function HEIGHTMAP-ADD-HILL (heightmap hx hy hradius hheight)
  • Function HEIGHTMAP-DIG-HILL (heightmap hx hy hradius hheight)
  • Function HEIGHTMAP-KERNEL-TRANSFORM (heightmap coords weights min-level max-level)
    * Arguments: - HEIGHTMAP :: pointer to a heightmap object. - COORDS :: a list of (X . Y) cons cells specifying coordinates relative to the cell being processed. For example (-1 . 0) is the cell to the west, (0 . 1) is the cell to the south, etc. - WEIGHTS :: a list of factors by which to scale the values in processed cells. The list must be the same length as COORDS. - MIN-LEVEL, MAX-LEVEL :: Cells are only processed if their values lies within these limits.
  • Function HEIGHTMAP-ADD-VORONOI (heightmap num-points coefs rng)
    * Arguments: - HEIGHTMAP :: pointer to a heightmap object. - NUM-POINTS :: number of Voronoi sites to create. - COEFS :: list of floats to use to scale the distance to each site. - RNG :: pointer to a random number generator object.
  • Function HEIGHTMAP-SCALE-FBM (heightmap noise mulx muly addx addy octaves delta scale)
  • Function HEIGHTMAP-GET-NORMAL (heightmap x y water-level)
    * Returns: a list of 3 floats, representing the normalised normal vector of the point at X, Y.
  • Function HEIGHTMAP-ISLANDIFY (heightmap sea-level rng)
  • Function MAP-NEW (width height)
    Return a new map object of the given dimensions.
  • Function MAP-SET-PROPERTIES (map x y transparent? walkable?)
    Set the properties of the map cell at =(X, Y)=. It is walkable if =walkable?= is true, and transparent if =transparent?= is true.
  • Function MAP-COMPUTE-FOV (map player-x player-y max-radius light-walls? algorithm)
    Compute field of view information for =MAP=, assuming the player is at =(PLAYER-X, PLAYER-Y)=, and using the field of view algorithm =ALGORITHM=.
  • Function MAP-IS-IN-FOV? (map x y)
    Return true if position =(X, Y)= on the map is visible.
  • Function MAP-SET-IN-FOV (map x y fov?)
    Set whether the cell at X, Y in =MAP= is in field of view.
  • Function MAP-IS-TRANSPARENT? (map x y)
    Return true if position =(X, Y)= on the map is set to be transparent.
  • Function MAP-IS-WALKABLE? (map x y)
    Return true if position =(X, Y)= on the map is set to be walkable.
  • Function MAP-CLEAR (map transparent? walkable?)
    Set all cells in =MAP= to be neither walkable nor transparent.
  • Function MAP-GET-WIDTH (map)
    Return the width of the map object =MAP=.
  • Function MAP-GET-HEIGHT (map)
    Return the height of the map object =MAP=.
  • Function MAP-GET-NB-CELLS (map)
    Return the number of cells in the map object =MAP=.
  • Function MAP-DELETE (map)
    Destroy the map object =MAP=.
  • Function MAP-COPY (map-src map-dest)
    Copy the map object =SRC= into the new map object =DEST=.
  • Function PATH-NEW-USING-MAP (map diagonal-cost)
    Return a new A* path object, using the map =MAP=.
  • Function PATH-NEW-USING-FUNCTION (xdim ydim callback user-data diagonal-cost)
    Return a new A* path object, which will call the function =CALLBACK= to calculate movement costs.
  • Function PATH-DELETE (a*-path)
    Delete an A* path object.
  • Function PATH-REVERSE (a*-path)
    Swap origin and destination for an A* path object.
  • Function PATH-COMPUTE (a*-path ox oy dx dy)
    Compute the path between the two points =(OX,OY)= and =(DX,DY)=, using the A* algorithm.
  • Function PATH-GET-ORIGIN (a*-path)
    Return the coordinates of the current origin of the A* path =PATH=.
  • Function PATH-GET-DESTINATION (a*-path)
    Return the coordinates of the current destination of the A* path =PATH=.
  • Function PATH-SIZE (a*-path)
    Return the number of steps in the path.
  • Function PATH-GET (a*-path index)
    Return the INDEXth step in the path from its current origin to its current destination.
  • Function PATH-WALK (a*-path recalc-when-needed?)
    Move one step along =PATH=. The path becomes one step shorter. Returns the coordinates of the new location.
  • Function PATH-IS-EMPTY? (a*-path)
    Return true if the path object is empty (has zero steps).
  • Function DIJKSTRA-NEW (map diagonal-cost)
    Return a new Dijkstra path object which uses =MAP=.
  • Function DIJKSTRA-NEW-USING-FUNCTION (xdim ydim callback user-data diagonal-cost)
    Return a new Dijkstra path object which calls the function =CALLBACK= to calculate movement costs.
  • Function DIJKSTRA-DELETE (dijkstra-path)
    Delete a Dijkstra path object.
  • Function DIJKSTRA-REVERSE (dijkstra-path)
    Swap origin and destination for a Dijkstra path object.
  • Function DIJKSTRA-COMPUTE (dijkstra-path rootx rooty)
    Compute paths leading to the point at =(ROOTX, ROOTY)=, using the Dijkstra algorithm.
  • Function DIJKSTRA-PATH-SET (dijkstra-path to-x to-y)
    Return true if a path can be found leading from the root node to the point at =(TO-X, TO-Y)=.
  • Function DIJKSTRA-SIZE (dijkstra-path)
    Return the number of steps in the path.
  • Function DIJKSTRA-GET-DISTANCE (dijkstra-path to-x to-y)
    Return the number of steps on the path leading from the root node to the point at =(TO-X, TO-Y)=.
  • Function DIJKSTRA-GET (dijkstra-path index)
    Return the INDEXth step in the path from its current origin to its current destination.
  • Function DIJKSTRA-IS-EMPTY? (dijkstra-path)
    Return true if the path object is empty (has zero steps).
  • Function DIJKSTRA-PATH-WALK (dijkstra-path)
    Move one step along =PATH=. The path becomes one step shorter. Returns the coordinates of the new location.
  • Function LINE-INIT (xfrom yfrom xto yto)
  • Function LINE-STEP (xcur ycur)
  • Function LINE-LINE (xfrom yfrom xto yto callback)
  • Function BSP-NEW-WITH-SIZE (x y w h)
  • Function BSP-REMOVE-SONS (node)
  • Function BSP-DELETE (node)
  • Function BSP-SPLIT-ONCE (node horizontal? pos)
  • Function BSP-SPLIT-RECURSIVE (node randomiser nb min-h-size min-v-size max-h-ratio max-v-ratio)
  • Function BSP-RESIZE (node x y w h)
  • Function BSP-LEFT (node)
  • Function BSP-RIGHT (node)
  • Function BSP-FATHER (node)
  • Function BSP-IS-LEAF? (node)
  • Function BSP-CONTAINS? (node cx cy)
  • Function BSP-FIND-NODE (node cx cy)
  • Function BSP-TRAVERSE-PRE-ORDER (node callback userdata)
  • Function BSP-TRAVERSE-IN-ORDER (node callback userdata)
  • Function BSP-TRAVERSE-POST-ORDER (node callback userdata)
  • Function BSP-TRAVERSE-LEVEL-ORDER (node callback userdata)
  • Function BSP-TRAVERSE-INVERTED-LEVEL-ORDER (node callback userdata)
  • Function HELLO-WORLD