bsp Module

Source code: bsp.py

The bsp module provides an Bsp class which derives from ReadWriteFile and is used to read and write Quake bsp data.

vgio.quake2.bsp.is_bspfile(filename)

Quickly see if a file is a bsp file by checking the magic number.

The filename argument may be a file for file-like object.

Parameters

filename – File to check as string or file-like object.

Returns

True if given file’s magic number is correct.

Bsp Class

class vgio.quake2.bsp.Bsp

Class for working with Bsp files

Example

Basic usage:

from vgio.quake2.bsp import Bsp
b = Bsp.open(file)
identity

Identity of the Bsp file. Should be b’IBSP’

version

Version of the Bsp file. Should be 38

entities

A string containing the entity definitions.

planes

A sequence of Plane objects used by the bsp tree data structure.

vertexes

A sequence of Vertex objects.

visibilities

A sequence of integers representing visibility data.

nodes

A sequence of Node objects used by the bsp tree data structure.

texture_infos

A sequence of TextureInfo objects.

faces

A sequence of Face objects.

lighting

A sequence of ints representing lighting data.

leafs

A sequence of Leaf objects used by the bsp tree data structure.

leaf_faces

A sequence of ints representing a consecutive list of faces used by the Leaf objects.

leaf_brushes

A sequence of ints representing a consecutive list of edges used by the Leaf objects.

edges

A sequence of Edge objects.

surf_edges

A sequence of ints representing a consecutive list of edges used by the Face objects.

models

A sequence of Model objects.

brushes

A sequence of Brush objects.

brush_sides

A sequence of BrushSide objects.

pop

Proof of purchase? Always 256 bytes of null data if present.

areas

A sequence of Area objects.

area_portals

A sequence of AreaPortal objects.

Bsp.__init__()

Constructs a Bsp object.

classmethod Bsp.open(file, mode='r')

Open a ReadWriteFile object where file can be a path to a file (a string), or a file-like object.

The mode parameter should be ‘r’ to read an existing file, ‘w’ to truncate and write a new file, or ‘a’ to append to an existing file.

open() is also a context manager and supports the with statement:

with ReadWriteFile.open('file.ext') as file:
    file.save('file2.ext')
Parameters

  • file – Either the path to the file, a file-like object, or bytes.

  • mode – An optional string that indicates which mode to open the file

Returns

An ReadWriteFile object constructed from the information read from the file-like object.

Raises

  • ValueError – If an invalid file mode is given.

  • TypeError – If attempting to write to a bytes object.

  • OSError – If the file argument is not a file-like object.

Bsp.close()

Closes the file pointer if possible. If mode is ‘w’ or ‘a’, the file will be written to.

Bsp.save(file)

Writes data to file.

Parameters

file – Either the path to the file, or a file-like object.

Raises

OSError – If file argument is not a file-like object.

Lump Class

class vgio.quake2.bsp.Lump(offset, length)

Class for representing a lump.

A lump is a section of data that typically contains a sequence of data structures.

offset

The offset of the lump entry from the start of the file.

length

The length of the lump entry.

Lump.__init__(offset, length)
classmethod Lump.read(file)
classmethod Lump.write(file, lump)

Plane Class

class vgio.quake2.bsp.Plane(normal_x, normal_y, normal_z, distance, type)

Class for representing a bsp plane

normal

The normal vector to the plane.

distance

The distance from world (0, 0, 0) to a point on the plane

type

Planes are classified as follows: 0: Axial plane aligned to the x-axis. 1: Axial plane aligned to the y-axis. 2: Axial plane aligned to the z-axis. 3: Non-axial plane roughly aligned to the x-axis. 4: Non-axial plane roughly aligned to the y-axis. 5: Non-axial plane roughly aligned to the z-axis.

Plane.__init__(normal_x, normal_y, normal_z, distance, type)
classmethod Plane.read(file)
classmethod Plane.write(file, plane)

Vertex Class

class vgio.quake2.bsp.Vertex(x, y, z)

Class for representing a vertex

A Vertex is an XYZ triple.

x

The x-coordinate

y

The y-coordinate

z

The z-coordinate

Vertex.__init__(x, y, z)
classmethod Vertex.read(file)
classmethod Vertex.write(file, vertex)

Node Class

class vgio.quake2.bsp.Node(plane_number, child_front, child_back, bounding_box_min_x, bounding_box_min_y, bounding_box_min_z, bounding_box_max_x, bounding_box_max_y, bounding_box_max_z, first_face, number_of_faces)

Class for representing a node

A Node is a data structure used to compose a bsp tree data structure. A child may be a Node or a Leaf.

plane_number

The number of the plane that partitions the node.

children

A two-tuple of the two sub-spaces formed by the partitioning plane.

Note

Child 0 is the front sub-space, and 1 is the back sub-space.

Note

If bit 15 is set, the child is a leaf.

bounding_box_min

The minimum coordinate of the bounding box containing this node and all of its children.

bounding_box_max

The maximum coordinate of the bounding box containing this node and all of its children.

first_face

The number of the first face in Bsp.mark_surfaces.

number_of_faces

The number of faces contained in the node. These are stored in consecutive order in Bsp.mark_surfaces starting at Node.first_face.

Node.__init__(plane_number, child_front, child_back, bounding_box_min_x, bounding_box_min_y, bounding_box_min_z, bounding_box_max_x, bounding_box_max_y, bounding_box_max_z, first_face, number_of_faces)
classmethod Node.read(file)
classmethod Node.write(file, node)

TextureInfo Class

class vgio.quake2.bsp.TextureInfo(s_x, s_y, s_z, s_offset, t_x, t_y, t_z, t_offset, flags, value, texture_name, next_texture_info)

Class for representing a texture info

s

The s vector in texture space represented as an XYZ three-tuple.

s_offset

Horizontal offset in texture space.

t

The t vector in texture space represented as an XYZ three-tuple.

t_offset

Vertical offset in texture space.

flags

A bitfield of surface behaviors.

value
texture_name

The path of the texture.

next_texture_info

For animated textures. Sequence will be terminated with a value of -1

TextureInfo.__init__(s_x, s_y, s_z, s_offset, t_x, t_y, t_z, t_offset, flags, value, texture_name, next_texture_info)
classmethod TextureInfo.read(file)
classmethod TextureInfo.write(file, texture_info)

Face Class

class vgio.quake2.bsp.Face(plane_number, side, first_edge, number_of_edges, texture_info, style_0, style_1, style_2, style_3, light_offset)

Class for representing a face

plane_number

The plane in which the face lies.

side

Which side of the plane the face lies. 0 is the front, 1 is the back.

first_edge

The number of the first edge in Bsp.surf_edges.

number_of_edges

The number of edges contained within the face. These are stored in consecutive order in Bsp.surf_edges starting at Face.first_edge.

texture_info

The number of the texture info for this face.

styles

A four-tuple of lightmap styles.

light_offset

The offset into the lighting data.

Face.__init__(plane_number, side, first_edge, number_of_edges, texture_info, style_0, style_1, style_2, style_3, light_offset)
classmethod Face.read(file)
classmethod Face.write(file, plane)

Leaf Class

class vgio.quake2.bsp.Leaf(contents, cluster, area, bounding_box_min_x, bounding_box_min_y, bounding_box_min_z, bounding_box_max_x, bounding_box_max_y, bounding_box_max_z, first_leaf_face, number_of_leaf_faces, first_leaf_brush, number_of_leaf_brushes)

Class for representing a leaf

contents

The content of the leaf. Affect the player’s view.

cluster

The cluster containing this leaf. -1 for no visibility info.

area

The area containing this leaf.

bounding_box_min

The minimum coordinate of the bounding box containing this node.

bounding_box_max

The maximum coordinate of the bounding box containing this node.

first_leaf_face

The number of the first face in Bsp.faces

number_of_leaf_faces

The number of faces contained within the leaf. These are stored in consecutive order in Bsp.faces at Leaf.first_leaf_face.

first_leaf_brush

The number of the first brush in Bsp.brushes

number_of_leaf_brushes

The number of brushes contained within the leaf. These are stored in consecutive order in Bsp.brushes at Leaf.first_leaf_brush.

Leaf.__init__(contents, cluster, area, bounding_box_min_x, bounding_box_min_y, bounding_box_min_z, bounding_box_max_x, bounding_box_max_y, bounding_box_max_z, first_leaf_face, number_of_leaf_faces, first_leaf_brush, number_of_leaf_brushes)
classmethod Leaf.read(file)
classmethod Leaf.write(file, leaf)

Edge Class

class vgio.quake2.bsp.Edge(vertex_0, vertex_1)

Class for representing a edge

vertexes

A two-tuple of vertexes that form the edge. Vertex 0 is the start vertex, and 1 is the end vertex.

Edge.__init__(vertex_0, vertex_1)
classmethod Edge.read(file)
classmethod Edge.write(file, edge)

Model Class

class vgio.quake2.bsp.Model(bounding_box_min_x, bounding_box_min_y, bounding_box_min_z, bounding_box_max_x, bounding_box_max_y, bounding_box_max_z, origin_x, origin_y, origin_z, head_node, first_face, number_of_faces)

Class for representing a model

bounding_box_min

The minimum coordinate of the bounding box containing the model.

bounding_box_max

The maximum coordinate of the bounding box containing the model.

origin

The origin of the model.

head_node

A four-tuple of indexes. Corresponds to number of map hulls.

visleafs

The number of leaves in the bsp tree?

first_face

The number of the first face in Bsp.mark_surfaces.

number_of_faces

The number of faces contained in the node. These are stored in consecutive order in Bsp.mark_surfaces starting at Model.first_face.

Model.__init__(bounding_box_min_x, bounding_box_min_y, bounding_box_min_z, bounding_box_max_x, bounding_box_max_y, bounding_box_max_z, origin_x, origin_y, origin_z, head_node, first_face, number_of_faces)
classmethod Model.read(file)
classmethod Model.write(file, model)

Brush Class

class vgio.quake2.bsp.Brush(first_side, number_of_sides, contents)
Brush.__init__(first_side, number_of_sides, contents)
classmethod Brush.read(file)
classmethod Brush.write(file, brush)

BrushSide Class

class vgio.quake2.bsp.BrushSide(plane_number, texture_info)
BrushSide.__init__(plane_number, texture_info)
classmethod BrushSide.read(file)
classmethod BrushSide.write(file, brush_side)

Area Class

class vgio.quake2.bsp.Area(number_of_area_portals, first_area_portal)
Area.__init__(number_of_area_portals, first_area_portal)
classmethod Area.read(file)
classmethod Area.write(file, area)

AreaPortal Class

class vgio.quake2.bsp.AreaPortal(portal_number, other_area)
AreaPortal.__init__(portal_number, other_area)
classmethod AreaPortal.read(file)
classmethod AreaPortal.write(file, area)