Billboards

Overview

Billboards are entities that display 2D sprites in 3D space. They include simple billboards, walls with directional textures, doors with animations, elevators for map transitions, and drops for item pickups.

Function Reference

billboard_new()

Creates a basic billboard entity.

t_billboard *billboard_new(t_game *game, t_ftm_window *window, char identifier);

game

t_game *

required

Pointer to the game instance

window

t_ftm_window *

required

Pointer to the window instance

identifier

char

required

Billboard identifier for configuration lookup

return

t_billboard *

Pointer to the newly created billboard, or NULL on allocation failure

wall_new()

Creates a wall entity with directional textures.

t_wall *wall_new(t_game *game, t_ftm_window *window, char identifier);

game

t_game *

required

Pointer to the game instance

window

t_ftm_window *

required

Pointer to the window instance

identifier

char

required

Wall identifier (use '1' for default walls)

return

t_wall *

Pointer to the newly created wall, or NULL on allocation failure

door_new_e()

Creates a door entity with opening/closing animations.

t_door *door_new_e(t_game *game, t_ftm_window *window, char identifier);

game

t_game *

required

Pointer to the game instance

window

t_ftm_window *

required

Pointer to the window instance

identifier

char

required

Door identifier for configuration lookup

return

t_door *

Pointer to the newly created door, or NULL on error. Returns NULL if required configuration (direction, sprites) is missing

elevator_new()

Creates an elevator entity for map transitions.

t_elevator *elevator_new(t_game *game, t_ftm_window *window, char identifier);

game

t_game *

required

Pointer to the game instance

window

t_ftm_window *

required

Pointer to the window instance

identifier

char

required

Elevator identifier for configuration lookup

return

t_elevator *

Pointer to the newly created elevator, or NULL on allocation failure

drop_new()

Creates a drop entity for item pickups.

t_drop *drop_new(t_game *game, t_ftm_window *window, char identifier);

game

t_game *

required

Pointer to the game instance

window

t_ftm_window *

required

Pointer to the window instance

identifier

char

required

Drop identifier for configuration lookup

return

t_drop *

Pointer to the newly created drop, or NULL on allocation failure

Structure Definitions

s_billboard

Basic billboard entity for displaying sprites in 3D space.

struct s_billboard
{
    t_entity        entity;
    bool            y_centered;
    t_sprite        **sprites;
};

entity

t_entity

Base entity structure

y_centered

bool

If true, sprite is vertically centered. If false, sprite is floor-aligned

sprites

t_sprite **

360-degree sprite array for omnidirectional viewing

s_wall

Wall entity with directional textures.

struct s_wall
{
    t_entity    entity;
    t_sprite    *north_sprite;
    t_sprite    *south_sprite;
    t_sprite    *west_sprite;
    t_sprite    *east_sprite;
};

entity

t_entity

Base entity structure

north_sprite

t_sprite *

Texture for north-facing wall surface

south_sprite

t_sprite *

Texture for south-facing wall surface

west_sprite

t_sprite *

Texture for west-facing wall surface

east_sprite

t_sprite *

Texture for east-facing wall surface

s_door

Door entity with animation and auto-close functionality.

struct s_door
{
    t_wall          wall;
    t_direction     direction;
    t_sprite        *opening_sprite;
    t_sprite        *door_sprite;
    t_sprite        *door_sides_sprite;
    bool            opened;
    bool            cant_close;
    t_time          auto_close_delay;
    t_time          last_opened_at;
    int             last_animation_index;
    bool            closeable;
    t_time          animation_delay;
    int             animation_frames;
    t_fta_audio     *open_sound;
    t_fta_audio     *close_sound;
};

wall

t_wall

Base wall structure

direction

t_direction

Door orientation (NORTH, SOUTH, EAST, WEST)

opening_sprite

t_sprite *

Animated sprite for opening/closing

door_sprite

t_sprite *

Source sprite for animation frames

door_sides_sprite

t_sprite *

Sprite for door edges/sides

opened

bool

Current open/closed state

cant_close

bool

Prevents closing if true

auto_close_delay

t_time

Delay before automatic closing (0 = manual close only)

last_opened_at

t_time

Timestamp when door was last opened

last_animation_index

int

Current frame of animation

closeable

bool

Whether door can be closed manually

animation_delay

t_time

Duration of animation in milliseconds

animation_frames

int

Number of animation frames (calculated from delay and FPS)

open_sound

t_fta_audio *

Sound played when door opens

close_sound

t_fta_audio *

Sound played when door closes

s_elevator

Elevator entity for transitioning between maps.

struct s_elevator
{
    t_wall      wall;
    char        *map_path;
};

wall

t_wall

Base wall structure

map_path

char *

Path to the map file to load when activated

s_drop

Drop entity for item pickups in the game world.

struct s_drop
{
    t_billboard billboard;
    t_item      *item;
    t_item      *prev_item;
    bool        auto_use;
    bool        auto_pickup;
};

billboard

t_billboard

Base billboard entity

item

t_item *

Pointer to the item contained in this drop

prev_item

t_item *

Previous item reference for state management

auto_use

bool

Whether the item is automatically used when picked up

auto_pickup

bool

Whether the item is automatically picked up when player is nearby

Constants

#define BILLBOARD_WIDTH 0.23
#define BILLBOARD_HEIGHT 0.23
#define WALL_INTERACTION_DISTANCE 2.0
#define DOOR_ANIMATION_FPS 6

BILLBOARD_WIDTH

double

Default billboard collision width

BILLBOARD_HEIGHT

double

Default billboard collision height

WALL_INTERACTION_DISTANCE

double

Maximum distance for wall interaction

DOOR_ANIMATION_FPS

int

Animation frames per second for door opening

Map Type Configuration

Billboard Configuration

T_STILL assets/sprites/tree
T_Y_CENTERED TRUE
T_TARGETABLE FALSE
T_TRANSPARENT TRUE

STILL

string

Path to 360-degree sprite assets for idle state

Y_CENTERED

string

"TRUE" for vertical centering, "FALSE" for floor alignment

TARGETABLE

string

"TRUE" if entity can be targeted by weapons/AI

TRANSPARENT

string

"TRUE" to enable transparency rendering

Wall Configuration

1_NO assets/textures/wall_north.bmp
1_SO assets/textures/wall_south.bmp
1_WE assets/textures/wall_west.bmp
1_EA assets/textures/wall_east.bmp

string

North-facing wall texture

string

South-facing wall texture

string

West-facing wall texture

string

East-facing wall texture

Note: Use identifier '1' for standard walls, or custom identifiers for special walls.

Door Configuration

D_DIRECTION NORTH
D_DOOR assets/sprites/door.bmp
D_SIDES assets/sprites/door_sides.bmp
D_AUTO_CLOSE_DELAY 3.0
D_CLOSEABLE TRUE
D_ANIMATION_DELAY 0.5
D_OPEN assets/sounds/door_open.wav
D_CLOSE assets/sounds/door_close.wav

DIRECTION

string

required

Door orientation: "NORTH", "SOUTH", "EAST", or "WEST"

DOOR

string

required

Path to door texture sprite (used to generate animation frames)

SIDES

string

Path to door edge/side texture

AUTO_CLOSE_DELAY

double

Seconds before automatic closing (0 = no auto-close)

CLOSEABLE

string

"TRUE" to allow closing, "FALSE" to keep open (default: TRUE)

ANIMATION_DELAY

double

Animation duration in seconds (multiplied by 10 internally)

OPEN

string

Path to door open sound effect

string

Path to door close sound effect

Elevator Configuration

E_MAP_PATH maps/level2.cub
E_NO assets/textures/elevator_north.bmp
E_SO assets/textures/elevator_south.bmp
E_WE assets/textures/elevator_west.bmp
E_EA assets/textures/elevator_east.bmp

MAP_PATH

string

Path to the map file to load when elevator is activated

Elevators also support all wall texture configuration options (NO, SO, WE, EA).

Door Animation System

Doors automatically generate animation frames based on configuration:

Animation Frames: Calculated as animation_delay * DOOR_ANIMATION_FPS
Frame Generation: Door sprite is sliced into frames based on width
Direction: North/South doors show opening sprite on north face, East/West doors show on west face
Sides: Door edge sprites are applied to perpendicular faces

Example

// Create a billboard tree
t_billboard *tree = billboard_new(game, window, 'T');
tree->y_centered = true;
tree->entity.coords = (t_coords){5.5, 5.5, 0};

// Create a wall
t_wall *wall = wall_new(game, window, '1');
wall->entity.coords = (t_coords){10.0, 10.0, 0};

// Create a door
t_door *door = door_new_e(game, window, 'D');
if (!door)
    return (error_handler("Failed to create door"));

door->auto_close_delay = 3000; // 3 seconds
door->entity.coords = (t_coords){15.0, 15.0, 0};

// Create an elevator
t_elevator *elevator = elevator_new(game, window, 'E');
elevator->map_path = "maps/level2.cub";
elevator->wall.entity.actionable = true;
elevator->wall.entity.coords = (t_coords){20.0, 20.0, 0};

// Open door (typically called from action handler)
if (!door->opened)
{
    door->opened = true;
    door->last_opened_at = ft_get_time();
    fta_play(door->open_sound);
}

Core

Rendering

Game Objects

Overview

Function Reference

billboard_new()

wall_new()

door_new_e()

elevator_new()

drop_new()

Structure Definitions

s_billboard

s_wall

s_door

s_elevator

s_drop

Constants

Map Type Configuration

Billboard Configuration

Wall Configuration

Door Configuration

Elevator Configuration

Door Animation System

Example

See Also

Build docs developers (and LLMs) love

Core

Rendering

Game Objects

​Overview

​Function Reference

​billboard_new()

​wall_new()

​door_new_e()

​elevator_new()

​drop_new()

​Structure Definitions

​s_billboard

​s_wall

​s_door

​s_elevator

​s_drop

​Constants

​Map Type Configuration

​Billboard Configuration

​Wall Configuration

​Door Configuration

​Elevator Configuration

​Door Animation System

​Example

​See Also

Build docs developers (and LLMs) love

Overview

Function Reference

billboard_new()

wall_new()

door_new_e()

elevator_new()

drop_new()

Structure Definitions

s_billboard

s_wall

s_door

s_elevator

s_drop

Constants

Map Type Configuration

Billboard Configuration

Wall Configuration

Door Configuration

Elevator Configuration

Door Animation System

Example

See Also