Raycaster library

A library for creating Wolfenstein style games.

File:
Raycaster.lib
Version:
1.3
Author:
Marcus Johansson and John Master

Contents

Details
Constants
Sub routines


Details

With the raycasting library and the RC Editor program you can create 3D games in the style of Wolfenstein (the first one). If you want more control it is possible to create games without using the editor. You could have a look at the 'Raycaster maze generation' example if you're interested. If you are using RC Editor, you don't need to care much about most of the subroutines presented below, because 'RC_LoadMap' takes care of the setup for you.

A NaaLaa raycasting "world" should be seen as a grid of cubes, where the side of every cube is 1. The world is represented by a 2D map/array with a couple of "layers":


Constants

Array indexing

Name
Description
RC_X
X coordinate.
RC_Z
Z coordinate.
RC_ANGLE
Angle.
RC_FLAG
Flag.

Array indexes for collision info

Name
Description
RC_NORTH
North.
RC_SOUTH
South.
RC_WEST
West.
RC_EAST
East.


Subroutines

General

Name
Parameters
Brief description
procedure
RC_InitView
fov#, renderW, renderH
Init view.
function
RC_LoadMap[][]
filename$
Load map.
function
RC_GetMapWidth
Get map width.
function
RC_GetMapHeight
Get map height.
procedure
RC_SetFog
r, g, b, zMin#, zMax#
Set fog.
procedure
RC_InitMap
w, h
Init map.
procedure
RC_Render
xpos#, zpos#, angle#, bobEffect#
Render view.
procedure
RC_Update
speed#
Update raycaster.
function
RC_GetImage
index
Get image from index.

Collision handling

Name
Parameters
Brief description
function
RC_Move#[]
dist#, xpos#, zpos#, dx#, dz#
Move with collision handling.
function
RC_GetCollisionInfo[]
Get collision information.
function
RC_ObstacleAt
x, z
Return true if position has an obstacle/wall.
function
RC_FacingWall
x#, z#, angle#
Return wall in front of position with respect to viewing angle.
function
RC_FacingPos[]
x#, z#, angle#
Return position in front of specified position with respect to viewing angle.
function
RC_Visible
xpos#, zpos#, dstx#, dstz#
Return true if there's no obstacle between two positions.

Walls

Name
Parameters
Brief description
function
RC_GetWall
x, z
Get wall.
function
RC_GetWallImage
x, z
Get wall image.
procedure
RC_SetWall
x, z, img
Set wall image.

Floor

Name
Parameters
Brief description
function
RC_GetFloor
x, z
Get floor.
function
RC_GetFloorImage
x, z
Get floor image.
procedure
RC_SetFloor
x, z, img
Set floor image.

Ceiling

Name
Parameters
Brief description
function
RC_GetCeiling
x, z
Get ceiling.
function
RC_GetCeilingImage
x, z
Get ceiling image.
procedure
RC_SetCeiling
x, z, img
Set ceiling image.

Flags

Name
Parameters
Brief description
function
RC_GetFlag
x, z
Get flag.
function
RC_GetFlagPos[]
flag
Get flag position.
procedure
RC_SetFlag
x, z, flag
Set flag value.

Items

Name
Parameters
Brief description
function
RC_GetItem
x, z
Return item.
procedure
RC_SetItem
x, z, item, obstacle
Set item value.
procedure
RC_RemoveItem
x, z
Remove item.

Objects

Name
Parameters
Brief description
procedure
RC_AddObject
id, img, x#, z#, y#, s#, ix, iz
Add visual object.
procedure
RC_ModifyObject
id, img, x#, z#, y#
Modify object.
procedure
RC_SetObjectImage
id, img
Set object image.
procedure
RC_SetObjectAdditive
id, value
Set additive property.
procedure
RC_SetObjectPos
id, x#, z#, y#
Set object position.
procedure
RC_RemoveObject
id
Remove object.
procedure
RC_ClearObjects
Clear objects.
function
RC_HasObject
id
Returns true if object exists.
procedure
RC_ObjChangeImages
currentImg, newImg
Change image for multiple objects.

Doors

Name
Parameters
Brief description
function
RC_GetDoor
x, z
Return door.
function
RC_DoorClosed
x, z
Return true if door at position is closed.
function
RC_DoorOpen
x, z
Return true if door at position is open.
procedure
RC_OpenDoor
x, z
Open door at position.
procedure
RC_CloseDoor
x, z
Close door at position.
procedure
RC_SetDoor
x, z, type, img, alongZ
Set door.
procedure
RC_ClearDoors
Clear doors.
procedure
RC_SetDoorSpeed
speed#
Set door speed.


Subroutine documentation

procedure RC_InitView ( fov#, renderW, renderH )

Must be called once before 'RC_Render'.

Parameter
Mode
Description
fov
In
Field of view.
renderW
In
Width of render area.
renderH
In
Height of render area.

[ Back ]


function RC_LoadMap[][] ( filename$ )

Load map created with RC_Editor. The returned array contains the starting position and angle set in the editor together with all set loader flags. The starting position is found at index 0 as [0][RC_X] and [0][RC_Z], and the angle at [0][RC_ANGLE]. The loader flags are stored as [n][RC_X], [n][RC_Z] and [n][RC_FLAG]. If the array is empty, the map could not be loaded.

Parameter
Mode
Description
filename
In
Filename.

Return value
Starting position and loader flags.

[ Back ]


function RC_GetMapWidth ( )

Get map width.

Return value
Map x size.

[ Back ]


function RC_GetMapHeight ( )

Get map height.

Return value
Map z size.

[ Back ]


procedure RC_SetFog ( r, g, b, zMin#, zMax# )

Sets fog properties and far clip plane.

Parameter
Mode
Description
r
In
Red color intensity.
g
In
Green color intensity.
b
In
Blue color intensity.
zMin
In
Fog start distance.
zMax
In
Fog end distance, also serves as far clip plane.

[ Back ]


procedure RC_InitMap ( w, h )

Create a new map, only relevant if you're not using RC Editor.

Parameter
Mode
Description
w
In
Width of map (x size).
h
In
Height of map (z size).

[ Back ]


procedure RC_Render ( xpos#, zpos#, angle#, bobEffect# )

Renders world as if seen some the specified position and angle. @parap bobEffect Always set to zero.

Parameter
Mode
Description
xpos
In
X position.
zpos
In
Z position.
angle
In
Angle.

[ Back ]


procedure RC_Update ( speed# )

This currently only has effect on door animations.

Parameter
Mode
Description
speed
In
Usually 1.0.

[ Back ]


function RC_GetImage ( index )

Return the image identifier for image at index from RC Editor.

Parameter
Mode
Description
index
In
Image index from RC Editor.

Return value
Image identifier.

[ Back ]


function RC_Move#[] ( dist#, xpos#, zpos#, dx#, dz# )

Try move "something" from specified position. If no collision occured, the [RC_X] and [RC_Z] fields of the returned arry will be 'xpos + dx' and 'zpos + dz'.

Parameter
Mode
Description
dist
In
Closest allowed distance to a wall, 0.1 is a good value.
xpos
In
Current x coordinate.
zpos
In
Current z coordinate.
dx
In
X movement.
dz
In
Z movement.

Return value
New position accessed as [RC_X] and [RC_Z].

[ Back ]


function RC_GetCollisionInfo[] ( )

The fields [RC_EAST], [RC_WEST], [RC_NORTH] and [RC_SOUTH] in the returned array will be set to either true or false, indicating if collisions occured or not.

Return value
Array with collision information.

[ Back ]


function RC_ObstacleAt ( x, z )

Return true if position has an obstacle/wall.

Parameter
Mode
Description
x
In
X map coordinate.
z
In
Z map coordinate.

Return value
True if obstacle.

[ Back ]


function RC_FacingWall ( x#, z#, angle# )

Return wall in front of position with respect to viewing angle.

Parameter
Mode
Description
x
In
X coordinate.
z
In
Z coordinate.
angle
In
Viewing angle.

Return value
Wall image index.

[ Back ]


function RC_FacingPos[] ( x#, z#, angle# )

Return position in front of specified position with respect to viewing angle.

Parameter
Mode
Description
x
In
X coordinate.
z
In
Z coordinate.
angle
In
Viewing angle.

Return value
Position accessed with [RC_X] and [RC_Z].

[ Back ]


function RC_Visible ( xpos#, zpos#, dstx#, dstz# )

Return true if there's no obstacle between two positions.

Parameter
Mode
Description
xpos
In
X start coordinate.
zpos
In
Z start coordinate.
dstx
In
X end coordinate.
dstz
In
Z end coordinate.

Return value
True if there's no obstacle.

[ Back ]


function RC_GetWall ( x, z )

Returns the wall at x, y. The returned value only makes sense if you're using the RC_Editor. It's the index of an image loaded in the editor, rather than the image identifier itself. You can use 'RC_GetImage' to convert the index to an image identifier.

Parameter
Mode
Description
x
In
X map coordinate.
z
In
Z map coordinate.

Return value
Image index.

[ Back ]


function RC_GetWallImage ( x, z )

Get wall image.

Parameter
Mode
Description
x
In
X map coordinate.
z
In
Z map coordinate.

Return value
Identifier of wall image.

[ Back ]


procedure RC_SetWall ( x, z, img )

Set wall image.

Parameter
Mode
Description
x
In
X map coordinate.
z
In
Z map coordinate.
img
In
Image identifier.

[ Back ]


function RC_GetFloor ( x, z )

Returns the floor at x, y. The returned value only makes sense if you're using the RC_Editor. It's the index of an image loaded in the editor, rather than the image identifier itself. You can use 'RC_GetImage' to convert the index to an image identifier.

Parameter
Mode
Description
x
In
X map coordinate.
z
In
Z map coordinate.

Return value
Image index.

[ Back ]


function RC_GetFloorImage ( x, z )

Get floor image.

Parameter
Mode
Description
x
In
X map coordinate.
z
In
Z map coordinate.

Return value
Identifier of floor image.

[ Back ]


procedure RC_SetFloor ( x, z, img )

Set floor image.

Parameter
Mode
Description
x
In
X map coordinate.
z
In
Z map coordinate.
img
In
Image identifier.

[ Back ]


function RC_GetCeiling ( x, z )

Returns the ceiling at x, y. The returned value only makes sense if you're using the RC_Editor. It's the index of an image loaded in the editor, rather than the image identifier itself. You can use 'RC_GetImage' to convert the index to an image identifier.

Parameter
Mode
Description
x
In
X map coordinate.
z
In
Z map coordinate.

Return value
Image index.

[ Back ]


function RC_GetCeilingImage ( x, z )

Get ceiling image.

Parameter
Mode
Description
x
In
X map coordinate.
z
In
Z map coordinate.

Return value
Identifier of ceiling image.

[ Back ]


procedure RC_SetCeiling ( x, z, img )

Set ceiling image.

Parameter
Mode
Description
x
In
X map coordinate.
z
In
Z map coordinate.
img
In
Image identifier.

[ Back ]


function RC_GetFlag ( x, z )

Get flag.

Parameter
Mode
Description
x
In
X map coordinate.
z
In
Z map coordinate.

Return value
Flag.

[ Back ]


function RC_GetFlagPos[] ( flag )

Returns position of the first founc occurance of a flag.

Parameter
Mode
Description
flag
In
Flag.

Return value
Position accessed with [RC_X] and [RC_Z].

[ Back ]


procedure RC_SetFlag ( x, z, flag )

Set flag value.

Parameter
Mode
Description
x
In
X map coordinate.
z
In
Z map coordinate.
flag
In
Flag.

[ Back ]


function RC_GetItem ( x, z )

Return item.

Parameter
Mode
Description
x
In
X map coordinate.
z
In
Z map coordinate.

Return value

[ Back ]


procedure RC_SetItem ( x, z, item, obstacle )

When loading a map from RC Editor, visual objects are automaticly connected to items. This procedure does no such thing.

Parameter
Mode
Description
x
In
X map coordinate.
z
In
Z map coordinate.
item
In
Item.
obstacle
In
True if item should be an obstacle.

[ Back ]


procedure RC_RemoveItem ( x, z )

Removes item at specified position. Also remove any connected visual object.

Parameter
Mode
Description
x
In
X map coordinate.
z
In
Z map coordinate.

[ Back ]


procedure RC_AddObject ( id, img, x#, z#, y#, s#, ix, iz )

Add a visual object to the world. An object is just an image with a position and size. If an object with the same id already exists, it will be replaced. Worth noting is the objects y position. If set to 0, the object will stand on the floor. If set to 1.0 - "the objects height", the object will hang from the ceiling. The object can be automaticly removed when an item at the specified position is removed. Set 'ix' and 'iz' to -1 if you're uninterested in this behaviour.

Parameter
Mode
Description
id
In
Identifier, must be positive and non-zero.
img
In
Image identifier of image to use.
x
In
X position.
z
In
Z position.
y
In
Y position.
s
In
The size, [0..1] of the longest side of the object.
ix
In
X map coordinate of item.
iz
In
Z map coordinate of item.

[ Back ]


procedure RC_ModifyObject ( id, img, x#, z#, y# )

Modify object.

Parameter
Mode
Description
id
In
Object identifier.
img
In
Image identifier.
x
In
X coordinate.
z
In
Z coordinate.
y
In
Y coordinate.

[ Back ]


procedure RC_SetObjectImage ( id, img )

Set object image.

Parameter
Mode
Description
id
In
Object identifier.
img
In
Image identifier.

[ Back ]


procedure RC_SetObjectAdditive ( id, value )

Set additive property.

Parameter
Mode
Description
id
In
Object identifier.
value
In
True for additive mode.

[ Back ]


procedure RC_SetObjectPos ( id, x#, z#, y# )

Set object position.

Parameter
Mode
Description
id
In
Object identifier.
x
In
X coordinate.
z
In
Z coordinate.
y
In
Y coordinate.

[ Back ]


procedure RC_RemoveObject ( id )

Remove object.

Parameter
Mode
Description
id
In
Object identifier.

[ Back ]


procedure RC_ClearObjects ( )

Remove all added visual objects.

[ Back ]


function RC_HasObject ( id )

Returns true if object exists.

Parameter
Mode
Description
id
In
Object identifier.

Return value

[ Back ]


procedure RC_ObjChangeImages ( currentImg, newImg )

Changes image from 'currentImg' to 'newImg' for all objects that use it.

Parameter
Mode
Description
currentImg
In
Current image.
newImg
In
Replacement image.

[ Back ]


function RC_GetDoor ( x, z )

Return the door at specified position. The returned value only makes sense if you're using RC Editor. It's the index of an image loaded in the editor. You can use 'RC_GetImage' to convert the index to an image id.

Parameter
Mode
Description
x
In
X map coordinate.
z
In
Z map coordinate.

Return value
Door image index.

[ Back ]


function RC_DoorClosed ( x, z )

Return true if door at position is closed.

Parameter
Mode
Description
x
In
X map coordinate.
z
In
Z map coordinate.

Return value
True if door is closed.

[ Back ]


function RC_DoorOpen ( x, z )

Return true if door at position is open.

Parameter
Mode
Description
x
In
X map coordinate.
z
In
Z map coordinate.

Return value
True if door is open.

[ Back ]


procedure RC_OpenDoor ( x, z )

Open door at position.

Parameter
Mode
Description
x
In
X map coordinate.
z
In
Z map coordinate.

[ Back ]


procedure RC_CloseDoor ( x, z )

Close door at position.

Parameter
Mode
Description
x
In
X map coordinate.
z
In
Z map coordinate.

[ Back ]


procedure RC_SetDoor ( x, z, type, img, alongZ )

Parameter
Mode
Description
x
In
X map coordinate.
z
In
Z map coordinate.
type
In
Value returned by RC_GetDoor, should be non-zero.
img
In
Image identifier.
alongZ
In
True if the door should open along z-axis, else x-axis will be used.

[ Back ]


procedure RC_ClearDoors ( )

Clear doors.

[ Back ]


procedure RC_SetDoorSpeed ( speed# )

Set movement speed of doors opening/closing. A door's movement parameter is in the range [0..1], and it's updated once every time you call 'RC_Update'.

Parameter
Mode
Description
speed
In
Speed.

[ Back ]


Generated with NLDoc 20160611.