Landlord Library

This file documents the main Landlord library. Not all of the functions declared in the headers are documented, just the ones most likely to be useful.

Home

#include <landlord/error.h>

const char *ll_progname;

Holds the program name or a null pointer.

void ll_set_progname(int argc, char **argv);

Sets the program name given argc/argv as passed to main, if possible.

void ll_fatal(const char *format, ...);

Issues an error message on stderr, using printf-style formatting, and terminates the program via exit.

void ll_fatale(int errno_value, const char *format, ...);

Issues an error message on stderr, using printf-style formatting but including an errno string, and terminates the program via exit.

#include <landlord/errors.h>

enum ll_error_code;

Error codes reported by the Landlord libraries. At least the following values are defined:

const char *ll_get_error_string(enum ll_error_code e);

Returns a pointer to a localized string describing error e. The string may be invalidated by the next call. For some error codes, the string will include the result of calling strerror(errno).

#include <landlord/game.h>

struct ll_game;

Game state. Contains at least the following fields:

int ncharacters;

struct ll_character *characters;

int me;

struct ll_map map;

int nterrain_types;

int *terrain_cost;

struct ll_display *display_state;

void (*repaint)(struct ll_game *);

void (*report)(struct ll_game *,
               const char *message);

void (*night_move)(struct ll_game *);

void (*night_battle)(struct ll_game *);

void (*moved)(struct ll_game *);

void (*describe)(struct ll_game *game,
                 char *buffer,
                 int bufsize);

void (*render_cell)(struct ll_pixmap *paper,
                    struct ll_game *game,
                    int xv, int yv,
                    enum ll_direction dir,
                    int xo, int yo,
                    const char *imgdir,
                    int xt, int yt);

ll_mapcell army_image;

ll_mapcell image_mask;

struct ll_character;

Character state. Contains at least the following fields:

int x, y;

enum ll_direction d;

int time;

int energy;

int army;

#define LL_NIGHT ...

Maximum value of time, indicating the end of the day.

#define LL_MAX_ENERGY ...

Maximum value of energy, indicating a fully rested character.

struct ll_game *ll_new_game(int ncharacters,
                            int mapwidth,
                            int mapheight,
                            int nterrain_types);

Allocate a new struct ll_game. The caller must fill in the map, initial character state, terrain costs, etc.

enum ll_error_code ll_move_character_direction(struct ll_game *g,
                                               int character,
                                               enum ll_direction d);

enum ll_error_code ll_move_character_location(struct ll_game *g,
                                              int character,
                                              int x, int y);

Move character in a given direction, or to a given location (which must be adjacent to their current location), updating time of day, energy, etc and repainting if it is the current character. This is the preferred interface for character movement.

These functions may return ll_cannot_move_off_map, ll_cannot_move_at_night or ll_not_enough_energy, which should be self-explanatory.

void ll_move_character(struct ll_game *g,
                       int character_number,
                       int x, int y);

Move a character to a given location, without updating anything.

int ll_check_location_for_character(struct ll_game *g,
                                    int x, int y,
                                    int lowest);

Look at location (x, y). If there are any characters at that location with character number >= lowest then return the lowest such character number. Otherwise return -1. May not work if characters are moved other than via the interfaces above!

void ll_game_night(struct ll_game *game);

Perform night-time processing. This moves non-player characters, resolves battles, and then updates time of day and energy for all characters. Note that this function does not do any repainting.

enum ll_error_code ll_input_game(struct ll_game *g,
                                 const char *path);

Read a game in from a file. On error, returns ll_read_error or ll_open_error (and does not modify the current game state). The messages for these error codes include the errno string.

enum ll_error_code ll_output_game(const struct ll_game *g,
                                  const char *path);

Write a game to a file. On error, returns ll_write_error, ll_open_error or ll_rename_error. The messages for these error codes include the errno string. Note that the game is written to a temporary file and renamed into place rather than directly overwriting the existing game.

The information saved is the map data, the state information for each character, and the current character number. Sizes and counts are not saved, nor are the terrain costs; these are not expected to be mutable.

#include <landlord/map.h>

enum ll_direction;

Enumeration of the 8 possible direction values, ll_north, ll_northeast, etc.

const char *const ll_direction_names[];

Array mapping direction numbers to their English names.

typedef ... ll_mapcell;

Type of a map cell. Guaranteed to be an unsigned integral type (currently unsigned char).

struct ll_map;

Map layout. Contains at least the following fields:

int width, height;

ll_mapcell edgecell;

ll_mapcell *data;

#define LL_MAPCELL(m, x, y) ...

Look up a map location. m should have type struct ll_map * (possibly qualified). The location must be within the map.

int ll_map_cell(const struct ll_map *map,
                int x, int y);

As above but works for locations off the edge too.

int ll_rotated_x(int x, int y,
                 enum ll_direction d);

int ll_rotated_y(int x, int y,
                 enum ll_direction d);

Rotate (x, y) by d eighth turns and return resulting X/Y value.

struct ll_pixmap *ll_draw_view(const char *imgdir,
                               struct ll_game *g,
                               int width, int height);

struct ll_pixmap *ll_draw_map(const char *imgdir,
                              struct ll_game *g,
			      int width, int height);

Draw a forward view or map for the current character into a pixmap of given size and return it. Images will be read from under imgdir.

void ll_render_cell(struct ll_pixmap *paper,
                    int xv, int yv,
                    enum ll_direction dir, 
                    int xo, int yo,
                    const char *imgdir,
                    int cell);

Draws image number cell from imgdir on pixmap paper. xv and yv are the centre of the view, dir is the direction of view and xo and yo are the unrotated offsets to the location being drawn.

#include <landlord/mem.h>

void *ll_malloc(size_t n);

Allocate n bytes of memory and return a pointer to them. If n is zero then the result may be a null pointer. If no memory is available, the program is terminated.

void *ll_realloc(void *p, size_t n);

Adjust the size of an allocation. The same caveats as above apply.

void ll_free(void *ptr);

Release allocated memory. ptr may safely be a null pointer even if the C library's free doesn't support this.

char *ll_strdup(const char *s);

Create a copy of a 0-terminated string via ll_malloc.

#include <landlord/pixmap.h>

Landlord contains its own drawing routines.

struct ll_pixel {
  unsigned char red;
  unsigned char green;
  unsigned char blue;
  unsigned char alpha;
};

The structure of a pixel.

const struct ll_pixel ll_solid_rgb[8];

8 basic colors. 1 is red, 2 is green and 4 is blue.

struct ll_pixmap;

Pixmap layout. Contains at least the following fields:

int width, height;

struct ll_pixel *pixels;

#define LL_PIXEL(p, x, y) ...

The pixel at the given location, as an lvalue (so you can use this macro to modify images as well as to inspect them).

struct ll_pixmap *ll_new_pixmap(int width,
                                int height);

Allocate a new pixmap of given dimensions. The initial image data is undefined.

void ll_free_pixmap(struct ll_pixmap *p);

Deallocate a pixmap.

struct ll_pixmap *ll_input_pixmap_png(const char *path);

Allocate a new pixmap and read it in from a PNG. Terminates the program on error.

void ll_compose_pixel(struct ll_pixel *pixel,
                      const struct ll_pixel *ink);

Compose ink onto pixel.

void ll_compose_pixmap(struct ll_pixmap *paper,
                       const struct ll_pixmap *brush,
                       int x, int y);

Compose brush onto paper. The brush may safely be partly or entirely off the edge of the paper.

void ll_pixmap_draw_rectangle(struct ll_pixmap *paper,
                              const struct ll_pixel *ink,
                              int xmin, int ymin,
                              int xmax, int ymax,
                              int fill);

Draw an optionally filled rectangle.

void ll_pixmap_draw_line(struct ll_pixmap *paper,
                         const struct ll_pixel *ink,
                         int x0, int y0,
                         int x1, int y1);

Draw a line.

struct ll_pixmap *ll_pixmap_scale(const struct ll_pixmap *old,
                                  int width, int height);

Create a new pixmap containing a scaled version of an old one.

struct ll_pixmap *ll_get_scaled_pixmap(const char *imgdir,
                                       int cell,
                                       int width, int height);

Load image number cell from imgdir and scale it to the given size. This function caches scaled pixmaps and is the preferred way of getting scaled copies of images on disk. If the file is not found then the program is terminated.

Copyright © 2002 Richard Kettlewell

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA