Xelf documentation reference

Table of Contents

About this document

(You can also browse a non-javascript flat HTML version of this document.)

This is the work-in-progress documentation for the Xelf game engine. Xelf stands for "extensible emacs-like facility". You can create active game objects called "nodes"; nodes can move and interact by being grouped into "buffers". Node and buffer classes can be subclassed to implement game logic and override default behavior. Other features include efficient quadtree-based collision detection, A-star pathfinding, gamepad support, and more.

Known issues:

  • Some things are not documented yet.
  • No tutorial yet. For now, use the plong and 3x0ng examples.

About Common Lisp

This document assumes that the user can use a command shell and a Lisp system. Using Xelf effectively will also require familiarity with Common Lisp development in general, and CLOS in particular.

Teaching Common Lisp is outside the scope of this document. The wikipedia page for Common Lisp has a reasonable capsule explanation of the syntax, with links to further resources. There's also Zach Beane's "Where to get help with Common Lisp".

Handling Lisp in your text editor

If you clicked the link in the last section to the Wikipedia page on Common Lisp and looked at the code examples, you probably noticed all the parentheses. The heavy use of parentheses marks Lisp off from other languages and makes it feel unfamiliar. But once you are able to read and write the basics, it all falls together naturally. The unusual syntax of Lisp is actually the key to many of its coolest features.

Matching up parentheses and indenting things properly is best handled automatically by a text editor with support for editing Lisp code, such as Vim, which can be used with Slimv — the Superior Lisp Interaction Mode for Vim. I myself use the GNU Emacs text editor along with Slime.

Using one of these options—Emacs with Slime, or Vim with Slimv—is probably the best way to develop and test Lisp code made with Xelf. With Slime or Slimv you can edit Lisp code efficiently, send commands to the underlying Lisp environment that Xelf is running in, or redefine methods and functions in order to alter object behaviors while the system is running.

Both Emacs and Vim are highly customizable development environments, not just text editors; in fact, I have developed and tested Xelf (all ~8KLOC) entirely with GNU Emacs as my IDE.

Furthermore, Emacs and Vim are Free software, will run on basically any platform, are of very high quality, and have large, friendly user communities.

That being said, you can edit Lisp code in basically any text editor, and it's quite possible that the text editor you already use has a plugin or script available for editing Lisp code and matching those parentheses. If you're unsure about Vim and Emacs, try looking around to see if you can find Lisp support for your existing editor.

Installing Xelf

1. Install required programs

If you are on GNU/Linux, you must install certain libraries through your distributions' software installer: sdl, sdl-image, sdl-mixer, sdl-gfx, and sdl-ttf. You may additionally need to install the corresponding *-dev versions of those packages.

You need a Common Lisp implementation, preferably SBCL.

2. Download Xelf

  mkdir ~/src 
  cd ~/src 
  git clone git://github.com/dto/xelf.git  

3. Install Quicklisp

It takes only a few moments to install Quicklisp, and this is the best way to download and install all the Common Lisp libraries that Xelf depends on—automatically.

After installing quicklisp you will see a notice about adding Quicklisp to your Lisp startup file with (ql:add-to-init-file).

Doing this will make Quicklisp load automatically when you start your Lisp implementation, but it isn't strictly required.

4. Start SBCL

Once SBCL is started, enter and execute the following Lisp expressions one at a time:

     ;; load dependencies via Quicklisp 
     (ql:quickload  
       '(:lispbuilder-sdl-mixer :lispbuilder-sdl-ttf  
       :lispbuilder-sdl-image :uuid :cl-opengl :cl-fad)) 

     ;; compile and load Xelf 
     (push #P"~/src/xelf/" asdf:*central-registry*) 
     (asdf:load-system :xelf) 

5. Compile the example game

At the shell:

  git clone git@github.com:dto/plong.git 

Then in SBCL;

     (push #P"~/src/plong/" asdf:*central-registry*)  
     (asdf:load-system :plong) 
     (setf xelf:*user-projects-directory* #P"~/src/") 
     (plong:plong) 

If this works, you're ready to start working with Xelf. If not, please report problems to me at dto@blocky.io. You can also visit the channel "#xelf" on irc.freenode.org.

Buffers

ADD-NODE (generic function)

(BUFFER NODE &OPTIONAL X Y (Z))

Add the mode NODE to the BUFFER. Optionally set the location with X,Y,Z.

COMPOSE (function)

(BUFFER1 BUFFER2)

Return a new buffer containing all the objects from both BUFFER1 and BUFFER2. The original buffers are destroyed.

COMPOSE-BELOW (function)

(&OPTIONAL BUFFER1 BUFFER2)

Return a new buffer containing all the objects from BUFFER1 and BUFFER2, with BUFFER2's objects pasted below those of BUFFER1. The original buffers are destroyed.

COMPOSE-BESIDE (function)

(&OPTIONAL BUFFER1 BUFFER2)

Return a new buffer containing all the objects from BUFFER1 and BUFFER2, with BUFFER2's objects pasted beside those of BUFFER1. The original buffers are destroyed.

CURRENT-BUFFER (function)

Return the currently active buffer.

DO-NODES (macro)

(SPEC &BODY BODY)

Iterate over the nodes in BUFFER, binding VAR to each node and evaluating the forms in BODY for each. SPEC is of the form (VAR BUFFER).

FOLLOW-WITH-CAMERA (generic function)

(BUFFER NODE)

Arrange for the BUFFER to follow NODE with the camera as it moves.

GET-NODES (generic function)

(BUFFER)

Collect all the nodes in the buffer as a list. Consider using DO-NODES instead.

GLIDE-WINDOW-TO (generic function)

(BUFFER X Y &OPTIONAL Z)

Configure window to glide smoothly to the point X,Y.

GLIDE-WINDOW-TO-NODE (generic function)

(BUFFER NODE)

Configure window to glide smoothly to the NODE.

INSERT (generic function)

(NODE &OPTIONAL X Y Z)

Add the NODE to the current buffer, optionally at X,Y,Z.

MOVE-TOWARD (generic function)

(NODE DIRECTION &OPTIONAL (STEPS))

Move the node STEPS units in compass direction DIRECTION.

MOVE-WINDOW (generic function)

(BUFFER DX DY &OPTIONAL DZ)

Move the buffer's window by DX,DY.

MOVE-WINDOW-TO (generic function)

(BUFFER X Y &OPTIONAL Z)

Move the buffer's window to X,Y.

MOVE-WINDOW-TO-NODE (generic function)

(BUFFER NODE)

Move the buffer's window to the node NODE.

ON-SCREEN-P (function)

(NODE)

Return non-nil when NODE touches the buffer's window bounding box.

PASTE (function)

(DESTINATION SOURCE &OPTIONAL (DX 0) (DY 0))

Copy the objects in SOURCE into DESTINATION with offset DX,DY.

REMOVE-NODE (generic function)

(BUFFER NODE)

Remove the object NODE from BUFFER.

SAVE-EXCURSION (variable)

SCALE-WINDOW (generic function)

(SELF &OPTIONAL (WINDOW-SCALE-X) (WINDOW-SCALE-Y))

SNAP-WINDOW-TO-NODE (generic function)

(BUFFER NODE)

Snap the window to the node NODE.

STACK-HORIZONTALLY (function)

(&REST BUFFERS)

Combine BUFFERS into a single buffer, with each buffer stacked horizontally.

STACK-VERTICALLY (function)

(&REST BUFFERS)

Combine BUFFERS into a single buffer, with each buffer stacked vertically.

STOP-FOLLOWING (generic function)

(BUFFER)

Stop all buffer following.

SWITCH-TO-BUFFER (function)

(BUFFER)

Switch to the buffer BUFFER.

TRANSFORM-WINDOW (function)

(&KEY (X 0) (Y 0) (Z 0) (SCALE-X 1.0) (SCALE-Y 1.0) (SCALE-Z 1.0))

TRIM (generic function)

(BUFFER)

Trim excess space from the buffer.

WINDOW-BOUNDING-BOX (generic function)

(BUFFER)

Return as multiple values the world-coordinate bounding box of the buffer's viewing window.

WINDOW-POINTER-X (function)

(&OPTIONAL (X *POINTER-X*))

Return the absolute x-coordinate of the mouse pointer.

WINDOW-POINTER-Y (function)

(&OPTIONAL (Y *POINTER-Y*))

Return the absolute y-coordinate of the mouse pointer.

WITH-BORDER (function)

(BORDER BUFFER)

Return a new buffer with the objects from BUFFER surrounded by a border of thickness BORDER units.

WITH-BUFFER (macro)

(BUFFER &REST BODY)

Evaluate the BODY forms in the BUFFER.

WITH-NEW-BUFFER (macro)

(&BODY BODY)

Evaluate the BODY forms in a new buffer.

Resources

DEFRESOURCE (macro)

(&REST ENTRIES)

Define a new resource.

A Xelf 'resource' is an image, sound, text, color, or font. Most resources will depend on a file for their data, such as a .PNG file for images and .WAV files for sounds.

A 'resource record' defines a resource. A resource record is a property list with the following elements:

:NAME A string; the name of the resource. (Required) :TYPE A keyword symbol identifying the data type. Valid types are :color :music :image :sample :ttf :font If TYPE is not given, Xelf will try to guess the file type based on the extension given as the NAME. :PROPERTIES Property list with extra data specific to resource TYPE. :FILE Name of file to load data from, if any. Relative to project directory. If FILE is not given, use the NAME.

FIND-RESOURCE (function)

(NAME &OPTIONAL NOERROR)

Obtain the resource named NAME, performing any necessary loading. Unless NOERROR is non-nil, signal an error when NAME cannot be found.

FIND-RESOURCE-OBJECT (function)

(NAME &OPTIONAL NOERROR)

Obtain the resource object named NAME, or signal an error if not found.

FIND-RESOURCE-PROPERTY (function)

(RESOURCE-NAME PROPERTY)

Read the value of PROPERTY from the resource RESOURCE-NAME.

INDEX-ALL-IMAGES (function)

Index all .PNG images in the project.

INDEX-ALL-SAMPLES (function)

Index all .WAV samples in the project.

INDEX-PENDING-RESOURCES (function)

INDEX-RESOURCE (function)

(RESOURCE)

Add the RESOURCE's record to the resource table. If a record with that name already exists, it is replaced.

LOAD-RESOURCE (function)

(RESOURCE)

Load the driver-dependent object of RESOURCE into the OBJECT field so that it can be fed to the console.

PRELOAD-RESOURCES (function)

Preload all currently indexed resources.

Pathfinding

CREATE-PATH (function)

(FINDER &KEY (HEIGHT *PATH-GRID-RESOLUTION*) (WIDTH *PATH-GRID-RESOLUTION*)

(BUFFER (CURRENT-BUFFER)))

FIND-PATH (function)

(PATH X0 Y0 X1 Y1)

Find a path from the starting point to the goal in PATH using A*. Returns a list of directional keywords an AI can follow to reach the goal.

FIND-PATH-WAYPOINTS (function)

(PATH X0 Y0 X1 Y1)

WILL-OBSTRUCT-P (generic function)

(NODE PATH-FINDER)

Returns non-nil when the node NODE will obstruct PATH-FINDER during path finding.

Events

BIND-EVENT (generic function)

(NODE EVENT METHOD-NAME)

Bind the EVENT to invoke the method specified in METHOD-NAME, with NODE as the sole argument to the method.

EVENT is a list of the form:

(NAME modifiers…)

NAME is either a keyword symbol identifying the keyboard key, or a string giving the Unicode character to be bound. MODIFIERS is a list of keywords like :control, :alt, and so on.

Examples:

 (bind-event self '(:up) 'move-up)
 (bind-event self '(:down) 'move-down)
 (bind-event self '(:q :control) 'quit)
 (bind-event self '(:escape :shift) 'menu)

See also `keys.lisp' for the full table of key and modifier symbols.

HANDLE-EVENT (generic function)

(NODE EVENT)

Attempt to find a binding for EVENT in NODE, and execute it if found.

MAKE-EVENT (function)

(CODE MODIFIERS)

Create an input event for the key CODE with MODIFIERS pressed. The argument CODE may be one of:

  • a keyword symbol naming the keyboard key, such as :RETURN or :SPACE (see also `make-key-symbol'.)
  • a one-character string, whose first character is the translated Unicode character being bound
  • an integer whose value is the unicode character code from SDL

or,

  • a cons of the form (key unicode) will be passed through unaltered.

NORMALIZE-EVENT (function)

(EVENT)

Convert EVENT to a normal form suitable for `equal' comparisons.

SEND-EVENT (function)

(EVENT)

Send the event EVENT to the currently active objects.

UNBIND-EVENT (generic function)

(NODE EVENT MODIFIERS)

Remove event binding for EVENT from NODE.

Movement

AIM (generic function)

(NODE HEADING)

Set the NODE's current heading to HEADING.

AIM-AT (generic function)

(NODE OTHER-NODE)

Set the NODE's heading to aim at the OTHER-NODE.

BACKWARD (generic function)

(NODE DISTANCE)

Move NODE backward DISTANCE units along the aim direction.

CENTER-POINT (generic function)

(NODE)

Return as multiple values the coordinates of the NODE's center point.

DIRECTION-DEGREES (function)

(DIRECTION)

Return the angle (in degrees) which DIRECTION points.

DIRECTION-HEADING (function)

(DIRECTION)

Return the angle (in radians) of the keyword DIRECTION.

DIRECTION-TO (generic function)

(NODE OTHER-NODE)

Returns the approximate keyword compass direction between NODE and OTHER-NODE.

DISTANCE (function)

(X1 Y1 X2 Y2)

Compute the distance between the points X1,Y1 and X2,Y2.

DISTANCE-BETWEEN (generic function)

(NODE OTHER-NODE)

Returns the distance between NODE and OTHER-NODE's center points.

FIND-BOUNDING-BOX (function)

(NODES)

Return as multiple values the minimal bounding box containing the NODES.

FIND-DIRECTION (function)

(X1 Y1 X2 Y2)

Return the heading (in radians) of the ray from Y1,X1 to Y2,X2.

FIND-HEADING (function)

(X0 Y0 X1 Y1)

Return the angle in radians of the ray from the point X0,Y0 to the point X1,Y1.

FORWARD (generic function)

(NODE DISTANCE)

Move the NODE forward along its current heading for DISTANCE units.

HEADING-BETWEEN (generic function)

(NODE OTHER-NODE)

Return the angle (in radians) of the ray from NODE to OTHER-NODE.

HEADING-DIRECTION (function)

(HEADING)

LOCATION (generic function)

(NODE)

Return as values the X,Y location of NODE.

MOVE (generic function)

(NODE HEADING DISTANCE)

Move the NODE toward HEADING by DISTANCE units.

MOVE-TO (generic function)

(NODE X Y &OPTIONAL Z)

Move the NODE to the point X,Y,Z.

OPPOSITE-DIRECTION (function)

(DIRECTION)

Return the direction keyword that is the opposite direction from DIRECTION.

OPPOSITE-HEADING (function)

(HEADING)

Return the heading angle opposite to HEADING.

STEP-IN-DIRECTION (function)

(X Y DIRECTION &OPTIONAL (N 1))

Return the point X Y moved by n squares in DIRECTION.

STEP-TOWARD-HEADING (generic function)

(NODE HEADING &OPTIONAL (DISTANCE))

Return as multiple values the point DISTANCE units at angle HEADING away from the center of NODE.

TURN-LEFT (generic function)

(NODE RADIANS)

Increase heading by RADIANS.

TURN-RIGHT (generic function)

(NODE RADIANS)

Decrease heading by RADIANS.

X (generic function)

(NODE)

Return the current x-coordinate of the NODE.

Y (generic function)

(NODE)

Return the current y-coordinate of the NODE.

Z (generic function)

(NODE)

Return the current z-coordinate of the NODE.

Drawing

*DEFAULT-TEXTURE-FILTER* (variable)

Filter used for drawing rendered outline fonts. Valid values are :mipmap (the default), :linear, and :nearest.

*NOMINAL-SCREEN-HEIGHT* (variable)

Nominal height of the window, in pixels.

*NOMINAL-SCREEN-WIDTH* (variable)

Nominal width of the window, in pixels.

*SCALE-OUTPUT-TO-WINDOW* (variable)

When non-nil, always show a fixed amount of the buffer when changing window size. Otherwise (the default) one onscreen pixel equals one unit of buffer space, so that more of the buffer shows if the window becomes larger.

*SCREEN-HEIGHT* (variable)

Physical height of the window, in pixels.

*SCREEN-WIDTH* (variable)

Physical width of the window, in pixels.

*USE-TEXTURE-BLENDING* (variable)

*WINDOW-POSITION* (variable)

Controls the position of the game window. Either a list of coordinates or the symbol :center.

*WINDOW-TITLE* (variable)

Title string for OS window.

ALIGN-TO-PIXELS (generic function)

(SELF)

CHANGE-IMAGE (generic function)

(NODE IMAGE)

Set the image of NODE to be IMAGE.

DRAW (generic function)

(NODE)

Draw the NODE.

DRAW-BOX (function)

(X Y WIDTH HEIGHT &KEY (COLOR "black") (ALPHA 1))

DRAW-IMAGE (function)

(NAME X Y &KEY (Z 0.0) (BLEND :ALPHA) (OPACITY 1.0) HEIGHT WIDTH)

Draw the image named NAME at x,y,z, sized HEIGHT, WIDTH, with blending mode BLEND.

DRAW-LINE (function)

(X0 Y0 X1 Y1 &KEY (COLOR "white"))

DRAW-TEXTURED-RECTANGLE (function)

(X Y Z WIDTH HEIGHT TEXTURE &KEY (BLEND :ALPHA) (OPACITY 1.0)

(VERTEX-COLOR "white")) Draw an OpenGL textured rectangle at X, Y, Z with width WIDTH and height HEIGHT. The argument TEXTURE is a texture returned by FIND-TEXTURE. BLEND sets the blending mode and can be one of :ALPHA, :ADDITIVE, :MULTIPLY.

DRAW-TEXTURED-RECTANGLE-* (function)

(X Y Z WIDTH HEIGHT TEXTURE &KEY U1 V1 U2 V2 ANGLE (BLEND :ALPHA)

(OPACITY 1.0) (VERTEX-COLOR "white"))

FIND-TEXTURE (function)

(NAME)

IMAGE-HEIGHT (function)

(IMAGE)

Return the height in pixels of IMAGE.

IMAGE-WIDTH (function)

(IMAGE)

Return the width in pixels of IMAGE.

RESIZE (generic function)

(NODE WIDTH HEIGHT)

Resize the NODE to be WIDTH by HEIGHT units.

RESIZE-TO-BACKGROUND-IMAGE (generic function)

(BUFFER)

Resize the buffer to fit its background image.

RESIZE-TO-IMAGE (generic function)

(NODE)

Resize the NODE to fit its image.

SCALE (generic function)

(SELF X-FACTOR &OPTIONAL Y-FACTOR)

SET-BLENDING-MODE (function)

(MODE)

USE-FILTER (function)

(FILTER)

Collision Detection

*QUADTREE-DEPTH* (variable)

BOUNDING-BOX (generic function)

(NODE)

Return as multiple values the coordinates of the bounding box for NODE. These are given in the order (TOP LEFT RIGHT BOTTOM).

BUILD-QUADTREE (function)

(BOUNDING-BOX0 &OPTIONAL (DEPTH *DEFAULT-QUADTREE-DEPTH*))

COLLIDE (generic function)

(NODE OTHER-NODE)

This method is invoked when NODE collides with OTHER-NODE.

COLLIDING-WITH-BOUNDING-BOX-P (function)

(SELF TOP LEFT RIGHT BOTTOM)

COLLIDING-WITH-P (generic function)

(NODE OTHER-NODE)

Return non-nil if NODE's bounding box touches OTHER-NODE's bounding box.

COLLIDING-WITH-RECTANGLE-P (generic function)

(NODE TOP LEFT WIDTH HEIGHT)

Return non-nil if NODE is colliding with the given rectangle.

HANDLE-COLLISION (generic function)

(NODE OTHER-NODE)

Wraparound for collision handling. You shouldn't need to use this explicitly.

INSTALL-QUADTREE (generic function)

(SELF)

QUADTREE-COLLIDE (function)

(OBJECT &OPTIONAL (TREE *QUADTREE*))

QUADTREE-DELETE (generic function)

(NODE &OPTIONAL (TREE))

QUADTREE-INSERT (generic function)

(NODE &OPTIONAL (TREE))

TOUCHING-POINT-P (generic function)

(NODE X Y)

Return non-nil if this NODE's bounding box touches the point X,Y.

WITH-QUADTREE (macro)

(QUADTREE &REST BODY)

Text

*BOLD* (variable)

Resource name of default boldface font.

*FONT* (variable)

The current font resource name. See also WITH-FONT. See also the file 'xelf/standard/index.xelf' for examples of font resource declarations.

*FONT-TEXTURE-FILTER* (variable)

Filter used for drawing rendered outline fonts. Valid values are :linear (the default), :mipmap, and :nearest.

*FONT-TEXTURE-SCALE* (variable)

Scaling factor for rendering of outline fonts. Use this when your game window might be enlarged to the point of blurring font textures that are too small.

*ITALIC* (variable)

Resource name of default italic font.

*MONOSPACE* (variable)

Name of the default monospace (fixed-width) font.

*SANS* (variable)

Name of the default sans-serif font.

*SERIF* (variable)

Name of the default serif font.

*USE-ANTIALIASED-TEXT* (variable)

When non-nil, render outline fonts with antialiasing. See also *FONT-TEXTURE-SCALE* and *FONT-TEXTURE-FILTER*.

CLEAR-TEXT-IMAGE-CACHE (function)

(&KEY (DELETE-TEXTURES T))

Free up texture memory used by rendered outline fonts.

DRAW-STRING (function)

(STRING X Y &KEY (COLOR *COLOR*) (FONT *FONT*) (Z 0))

Render the string STRING at x,y with color COLOR and font FONT.

DRAW-STRING-BLENDED (variable)

DRAW-STRING-SHADED (variable)

DRAW-STRING-SOLID (variable)

FONT-HEIGHT (function)

(FONT)

Height of a line of text in font FONT.

FONT-TEXT-WIDTH (function)

(STRING &OPTIONAL (FONT *FONT*))

Width of STRING when rendered in FONT.

FONT-WIDTH (function)

(FONT)

Character with of a bitmap font FONT. Signals an error when called on an outline font.

WITH-FONT (macro)

(FONT &REST BODY)

Evaluate forms in BODY with FONT as the current font.

Lifecycle

DESTROY (generic function)

(NODE)

Destroy this NODE and remove it from any buffers.

UPDATE (generic function)

(NODE)

Update the node's game logic for one frame.

Keyboard

DISABLE-KEY-REPEAT (function)

Disable key repeat.

ENABLE-KEY-REPEAT (function)

(&OPTIONAL (DELAY *KEY-REPEAT-DELAY*) (INTERVAL *KEY-REPEAT-INTERVAL*))

Enable key repeat after DELAY milliseconds, repeating at INTERVAL milliseconds.

HOLDING-CONTROL (function)

Returns non-nil if one of the CONTROL keys is pressed.

HOLDING-SHIFT (function)

Returns non-nil if one of the SHIFT keys is pressed.

KEYBOARD-DOWN-P (function)

(KEY)

Returns t if the KEY is depressed.

KEYBOARD-HELD-P (function)

(KEY)

Returns the duration in seconds that KEY has been depressed over a number of game loops.

KEYBOARD-KEYS-DOWN (function)

Returns a list of the keys that are depressed.

KEYBOARD-MODIFIER-DOWN-P (function)

(MOD)

Returns t if the modifier key MOD is depressed.

KEYBOARD-MODIFIERS (function)

Returns a list of the modifier keys that are depressed.

KEYBOARD-PRESSED-P (function)

(KEY)

Returns t if KEY has just been depressed in the current game loop.

KEYBOARD-RELEASED-P (function)

(KEY)

Returns t if KEY has just been released in the current game loop.

KEYBOARD-TIME-IN-CURRENT-STATE (function)

(KEY)

Returns the duration in seconds that KEY is either pressed or depressed.

KEYBOARD-TIME-IN-PREVIOUS-STATE (function)

(KEY)

Returns the duration in seconds that KEY was in its previous state either pressed or depressed.

Mouse

*POINTER-X* (variable)

Current window-relative x-coordinate of the mouse pointer.

*POINTER-Y* (variable)

Current window-relative y-coordinate of the mouse pointer.

ALTERNATE-TAP (generic function)

(SELF X Y)

HANDLE-POINT-MOTION (generic function)

(SELF X Y)

PRESS (generic function)

(SELF X Y &OPTIONAL BUTTON)

RELEASE (generic function)

(SELF X Y &OPTIONAL BUTTON)

SCROLL-DOWN (generic function)

(SELF)

SCROLL-LEFT (generic function)

(SELF)

SCROLL-RIGHT (generic function)

(SELF)

SCROLL-TAP (generic function)

(SELF X Y)

SCROLL-UP (generic function)

(SELF)

TAP (generic function)

(SELF X Y)

Joystick

*DEFAULT-JOYSTICK-PROFILE* (variable)

*GENERIC-JOYSTICK-MAPPING* (variable)

*JOYSTICK-AXIS-DEAD-ZONE* (variable)

*JOYSTICK-AXIS-SIZE* (variable)

*JOYSTICK-BUTTON-SYMBOLS* (variable)

*JOYSTICK-DEAD-ZONE* (variable)

*JOYSTICK-DEVICE* (variable)

The SDL device id of the current joystick.

*JOYSTICK-DEVICE-NUMBER* (variable)

The number of the current joystick.

*JOYSTICK-MAPPING* (variable)

*USER-JOYSTICK-PROFILE* (variable)

ANALOG-STICK-HEADING (function)

(&OPTIONAL (STICK (JOYSTICK-LEFT-ANALOG-STICK)) (ID 0))

ANALOG-STICK-PRESSED-P (function)

(&OPTIONAL (STICK (JOYSTICK-LEFT-ANALOG-STICK)) (ID 0))

ANALOG-STICK-PRESSURE (function)

(&OPTIONAL (STICK (JOYSTICK-LEFT-ANALOG-STICK)) (ID 0))

BUTTON-TO-SYMBOL (function)

(BUTTON)

IS-JOYSTICK-EVENT (variable)

IS-RAW-JOYSTICK-EVENT (variable)

JOYSTICK-AXIS-PRESSED-P (function)

(AXIS &OPTIONAL (ID 0))

JOYSTICK-AXIS-RAW-VALUE (function)

(AXIS &OPTIONAL (ID 0))

JOYSTICK-AXIS-VALUE (function)

(AXIS &OPTIONAL (ID 0))

JOYSTICK-BUTTON-PRESSED-P (function)

(BUTTON &OPTIONAL (ID 0))

JOYSTICK-BUTTON-STATE (function)

(BUTTON &OPTIONAL (ID 0))

JOYSTICK-BUTTONS (function)

(&OPTIONAL (PROFILE (JOYSTICK-PROFILE)))

JOYSTICK-EVENT-P (function)

(EVENT)

Return non-nil if the EVENT is a joystick event.

JOYSTICK-LEFT-ANALOG-STICK (function)

(&OPTIONAL (PROFILE (JOYSTICK-PROFILE)))

JOYSTICK-NAME (function)

(&OPTIONAL (PROFILE (JOYSTICK-PROFILE)))

JOYSTICK-PROFILE (function)

JOYSTICK-RIGHT-ANALOG-STICK (function)

(&OPTIONAL (PROFILE (JOYSTICK-PROFILE)))

JOYSTICK-TYPE (function)

(&OPTIONAL (PROFILE (JOYSTICK-PROFILE)))

LEFT-ANALOG-STICK-HEADING (function)

(&OPTIONAL (ID 0))

LEFT-ANALOG-STICK-PRESSED-P (function)

(&OPTIONAL (ID 0))

LEFT-ANALOG-STICK-PRESSURE (function)

(&OPTIONAL (ID 0))

NUMBER-OF-JOYSTICKS (function)

RESET-JOYSTICK (function)

(&OPTIONAL (DEVICE 0))

Re-open the joystick device and re-initialize the state.

RIGHT-ANALOG-STICK-HEADING (function)

(&OPTIONAL (ID 0))

RIGHT-ANALOG-STICK-PRESSED-P (function)

(&OPTIONAL (ID 0))

RIGHT-ANALOG-STICK-PRESSURE (function)

(&OPTIONAL (ID 0))

Sound

*FREQUENCY* (variable)

*OUTPUT-CHANNELS* (variable)

*OUTPUT-CHUNKSIZE* (variable)

HALT-MUSIC (function)

(&OPTIONAL (FADE-MILLISECONDS 0))

Stop all music playing.

HALT-SAMPLE (function)

(CHANNEL &REST ARGS)

Stop playing the sample on channel CHANNEL.

PLAY-MUSIC (function)

(MUSIC-NAME &REST ARGS)

Begin playing the music resource MUSIC-NAME. If the resource MUSIC-NAME has the property :volume, its value is used as the volume of the music.

PLAY-SAMPLE (function)

(SAMPLE-NAME &REST ARGS)

When sound is enabled, play the sample resource SAMPLE-NAME. If successful, returns the integer CHANNEL number playing the sound.

SEEK-MUSIC (function)

(POSITION)

SET-MUSIC-VOLUME (function)

(NUMBER)

Set the mixer music volume between 0 (silent) and 255 (full volume).

Math

*DIRECTIONS* (variable)

List of keywords representing the eight compass directions.

CFLOAT (function)

(F)

HEADING-DEGREES (function)

(RADIANS)

PERCENT-OF-TIME (macro)

(PERCENT &BODY BODY)

Evaluate the BODY forms PERCENT percent of the time.

RADIAN-ANGLE (function)

(DEGREES)

Convert DEGREES to radians.

RANDOM-CHOOSE (function)

(SET)

Randomly choose one element of the list SET and return it.

RENDER-PLASMA (function)

(HEIGHT WIDTH &KEY (GRAININESS 1.0) ARRAY)

Return a rectangle subdivision noise field with WIDTH,HEIGHT.

SECONDS->FRAMES (function)

(SECONDS)

Return the time in SECONDS as an integer number of frames. Based on the current *FRAME-RATE*.

Hooks

*AFTER-LOAD-PROJECT-HOOK* (variable)

*AFTER-STARTUP-HOOK* (variable)

*EVENT-HANDLER-FUNCTION* (variable)

Function to be called with input events. Keyboard, mouse, and joystick events are represented as 'event lists' of the form:

(STRING . MODIFIERS)

where STRING is a string representing the key or button, and MODIFIERS is a list of key modifier symbols like :shift, :control, :alt, and so on.

The modifier list is sorted; thus, events can be compared for equality with `equal' and used as hashtable keys.

*EVENT-HOOK* (variable)

*MESSAGE-FUNCTION* (variable)

*MESSAGE-HISTORY* (variable)

*MESSAGE-HOOK-FUNCTIONS* (variable)

*MESSAGE-LOGGING* (variable)

*NEXT-UPDATE-HOOK* (variable)

*RESIZE-HOOK* (variable)

Hook to be run after user resizes window.

*UPDATE-FUNCTION* (variable)

ADD-HOOK (function)

(HOOK FUNC)

Hooks are special variables whose names are of the form `*foo-hook*' and whose values are lists of functions taking no arguments. The functions of a given hook are all invoked (in list order) whenever the hook is run with `run-hook'.

This function arranges for FUNC to be invoked whenever HOOK is triggered with `run-hook'. The function should have no arguments.

ADD-TO-LIST (function)

(LIST ELEMENT)

Add the item ELEMENT to the list LIST.

RESET-MESSAGE-FUNCTION (function)

RUN-HOOK (function)

(HOOK)

Call all the functions in HOOK, in list order.

System

*COPYRIGHT-NOTICE* (variable)

Copyright notices for Xelf, its dependencies, and the current Lisp implementation.

*EXECUTABLE* (variable)

Non-nil when running Xelf from a saved binary image.

*FRAME-RATE* (variable)

Requested frame rate.

*FULLSCREEN* (variable)

When non-nil, attempt to use fullscreen mode.

*PROJECT* (variable)

The name of the current project. This is set by OPEN-PROJECT; use that instead.

*PROJECT-DIRECTORIES* (variable)

List of directories where XELF will search for projects. Directories are searched in list order.

*PROJECT-PATH* (variable)

The pathname of the currently opened project.

*RESIZABLE* (variable)

When non-nil, game window will be resizable.

*UPDATES* (variable)

The number of game loop updates since startup.

*USE-SOUND* (variable)

Non-nil (the default) is to use sound. Nil disables sound.

AT-NEXT-UPDATE (macro)

(&BODY BODY)

Run the forms in BODY at the next game loop update.

CURRENT-DIRECTORY (function)

Returns the pathname of the current directory.

DUPLICATE (generic function)

(NODE &REST INITARGS &ALLOW-OTHER-KEYS)

Make a copy of this NODE.

MAKE-DIRECTORY-MAYBE (function)

(NAME)

MESSAGE (function)

(FORMAT-STRING &REST ARGS)

Print a log message by passing the arguments to `*message-function'. When the variable `*message-logging*' is nil, this output is disabled.

OPEN-PROJECT (function)

(&OPTIONAL (PROJECT *PROJECT*) PARAMETERS)

Set the current project to PROJECT.

QUIT (function)

(&OPTIONAL SHUTDOWN)

Exit the game engine.

READ-SEXP-FROM-FILE (function)

(FILENAME)

WITH-SESSION (macro)

(&BODY BODY)

Starts up Xelf, runs the BODY forms, and starts the main game loop. Xelf will exit after the game loop terminates.

WRITE-SEXP-TO-FILE (function)

(FILENAME SEXP)