srctools.vmf
VMF Library
Wraps property_parser tree in a set of classes which smartly handle specifics of VMF files.
-
srctools.vmf.
conv_kv
(val: Union[str, int, bool, float, VecBase, Vec_tuple, Tuple[float, float, float], Angle, FrozenAngle, Matrix, FrozenMatrix],) str Convert a type into a string matching Valve’s syntax.
-
srctools.vmf.
make_overlay
(vmf: VMF,) Entity
normal: Vec,
origin: Vec,
uax: Vec,
vax: Vec,
material: str,
surfaces: Iterable[Side],
u_repeat: float = 1,
v_repeat: float = 1,
swap: bool = False,
render_order: int = 0, Generate an overlay on an axis-aligned surface.
Parameters: - origin – The center point of the overlay.
- uax – The direction and distance for the texture’s width (
right
). - vax – The direction and distance for the texture’s height (
up
). - normal – The normal of the surface.
- material – The material used.
- u_repeat – Defines how many times to repeat the texture in the U direction.
- v_repeat – Defines how many times to repeat the texture in the V direction.
- swap – If true, the texture will be rotated
90
.
-
class
srctools.vmf.
VMF
() Represents a VMF file, and holds counters for various IDs used.
Has functions for searching for specific entities or brushes, and converts to/from a property_parser tree.
The dictionaries by_target and by_class allow quickly getting a set of entities with the given class or targetname.
-
add_ent
(item: Entity) None Add an entity to the map.
The entity should have been created with this VMF as a parent.
-
remove_ent
(item: Entity) None Remove an entity from the map.
After this is called, the entity will no longer be exported. The object still exists, so it can be reused.
-
create_ent
(classname: str,) Entity
**kargs: Union[str, int, bool, float, VecBase, Vec_tuple, Tuple[float, float, float], Angle, FrozenAngle, Matrix, FrozenMatrix], Convenience method to allow creating point entities.
This constructs an entity, adds it to the map, and then returns it. A classname must be passed!
-
export
() str -
export
() None Serialises the object’s contents into a VMF file.
- If no file is given the map will be returned as a string.
- By default, this will increment the map’s version - disable inc_version to suppress this.
- If minimal is True, several blocks will be skipped (Viewsettings, cameras, cordons and visgroups)
- disp_multiblend controls whether displacements produce their multiblend data (added in ASW), or if it is stripped.
- named_cordons controls if multiple cordons may be used (post L4D), or if only a single cordon is allowed.
-
iter_ents
(**cond: str) Iterator[Entity] Iterate through entities having the given keyvalue values.
-
iter_ents_tags
() Iterator[Entity] Iterate through all entities.
The returned entities must have exactly the given keyvalue values, and have keyvalues containing the tags.
-
iter_inputs
(name: str) Iterator[Output] Loop through all Outputs which target the named entity.
- Allows using * at beginning/end
-
search
(name: str) Iterator[Entity] Yield all entities that fit this search string.
This can be the exact targetname, end-* matching, or the exact classname.
-
-
class
srctools.vmf.
Camera
(vmf_file: VMF, pos: Vec, targ: Vec) Represents one of several cameras which can be swapped between.
-
class
srctools.vmf.
Cordon
() Represents one cordon volume.
-
class
srctools.vmf.
VisGroup
(vmf: VMF,)
name: str,
id: int = -1,
color: Vec = _Nothing.NOTHING,
child_groups: List[VisGroup] = _Nothing.NOTHING, Defines one visgroup.
-
class
srctools.vmf.
Solid
(map: VMF,)
id: int = -1,
sides: List[Side] = _Nothing.NOTHING,
visgroup_ids=(),
hidden: bool = False,
group_id: Optional[int] = None,
vis_shown: bool = True,
vis_auto_shown: bool = True,
cordon_solid: Optional[int] = None,
editor_color: Vec = _Nothing.NOTHING, A single brush, serving as both world brushes and brush entities.
-
copy
(des_id: int = -1,) Solid
vmf_file: Optional[VMF] = None,
side_mapping: MutableMapping[int, int] = srctools.EmptyMapping,
keep_vis: bool = True, Duplicate this brush.
-
-
class
srctools.vmf.
Side
(vmf_file: VMF,)
planes: List[Vec],
des_id: int = -1,
lightmap: int = 16,
smoothing: int = 0,
mat: str = 'tools/toolsnodraw',
rotation: float = 0,
uaxis: Optional[UVAxis] = None,
vaxis: Optional[UVAxis] = None,
disp_power: Literal[0, 1, 2, 3, 4] = 0, A brush face.
-
classmethod
parse
(vmf_file: VMF, tree: Keyvalues) Side Parse the property tree into a Side object.
-
copy
(des_id: int = -1,) Side
vmf_file: Optional[VMF] = None,
side_mapping: MutableMapping[int, int] = srctools.EmptyMapping, Duplicate this brush side.
des_id is the id which is desired for the new side. map is the VMF to add the new side to (defaults to the same map). If passed, side_mapping will be updated with a old -> new ID pair.
-
export
() None Generate the strings required to define this side in a VMF.
- disp_multiblend controls whether displacements produce their multiblend data (added in CSGO), or if it is skipped.
-
translate
(diff: Vec) None Move this side by the specified vector.
- A tuple can be passed in instead if desired.
-
disp_get_tri_verts
(x: int, y: int) Tuple[DispVertex, DispVertex, DispVertex, DispVertex, DispVertex, DispVertex] Return the locations of the triangle vertexes.
This is a set of 6 verts, representing the two triangles in order. See 2013 SDK src/public/builddisp.cpp:896-965.
-
plane_desc
() str Return a string which describes this face.
This is for use in texture randomisation.
-
property
scale
Set both scale attributes easily.
-
property
offset
Set both offset attributes easily.
-
classmethod
-
class
srctools.vmf.
Entity
(vmf_file: VMF,)
keys: Mapping[str, Union[str, int, bool, float, VecBase, Vec_tuple, Tuple[float, float, float], Angle, FrozenAngle, Matrix, FrozenMatrix]] = srctools.EmptyMapping,
fixup: Iterable[FixupValue] = (),
ent_id: int = -1,
outputs: Iterable[Output] = (),
solids: Iterable[Solid] = (),
hidden: bool = False,
groups: Iterable[int] = (),
vis_ids: Iterable[int] = (),
vis_shown: bool = True,
vis_auto_shown: bool = True,
logical_pos: Optional[str] = None,
editor_color: Union[Vec, Tuple[int, int, int]] = (255, 255, 255),
comments: str = '', A representation of either a point or brush entity.
Creation: * Entity(args) for a brand-new Entity * Entity.parse(property) if reading from a VMF file * ent.copy() to duplicate an existing entity
Supports [] operations to read and write keyvalues. To read instance $replace values operate on entity.fixup[]
-
property
keys
: _KeyDict Access the internal keyvalues dict.
This use is deprecated, the entity is a MutableMapping. It can also be called to get a keys view, as with other mappings.
-
property
fixup
: EntityFixup Access $replace variables on instances.
-
copy
(des_id: int = -1,) Entity
vmf_file: Optional[VMF] = None,
side_mapping: MutableMapping[int, int] = srctools.EmptyMapping,
keep_vis: bool = True, Duplicate this entity entirely, including solids and outputs.
-
static
parse
() Entity Parse a property tree into an Entity object.
_worldspawn indicates if this is the worldspawn entity, which additionally contains the entity group definitions.
-
export
() None Generate the strings needed to create this entity.
- disp_multiblend controls whether displacements produce their multiblend data (added in ASW), or if it is skipped.
- _is_worldspawn is used interally to generate the special worldspawn block.
-
make_unique
(unnamed_prefix: str = '') Entity Ensure this entity is uniquely named, by adding a numeric suffix.
If the entity doesn’t start with a name, it will use the parameter.
-
get
(key: str, default: Union[str, T] = '') Union[str, T] Allow using [] syntax to search for keyvalues.
- This will return ‘’ if the value is not present.
- It ignores case-matching, but will use the first given version of a key.
- If used via Entity.get() the default argument is available.
- A tuple can be passed for the default to be set, inside the [] syntax.
-
property
-
class
srctools.vmf.
EntityGroup
() Represents the ‘group’ blocks in worldspawn.
This allows the grouping of brushes.
-
classmethod
parse
(vmf_file: VMF, props: Keyvalues) EntityGroup Parse an entity group from the VMF file.
-
copy
(vmf: Optional[VMF] = None) EntityGroup Duplicate an entity group.
-
classmethod
-
class
srctools.vmf.
DispFlag
(value) Bases:
Flag
Per-displacement flags, configuring collisions.
Does NOT match the file values, since those are inverted.
-
COLL_NONE
= 0
-
COLL_PHYSICS
= 1
-
COLL_PLAYER_NPC
= 2
-
COLL_BULLET
= 4
-
COLL_ALL
= 7
-
SUBDIV
= 8
-
SUBDIV_COLL_ALL
= 15
-
-
class
srctools.vmf.
TriangleTag
(value) Bases:
Flag
Two flags set on all displacement triangles.
If walkable, it is shallow enough to stand on. If buildable, TF2 Engineers can place buildings.
-
STEEP
= 0
-
WALKABLE
= 1
-
BUILDABLE
= 9 Alias:
FLAT
-
-
class
srctools.vmf.
PrismFace
() Return value for VMF.make_prism().
This can be inded with an axis-aligned
Vec
or 3-tuple normal to fetch a side.
-
class
srctools.vmf.
UVAxis
() Values saved into Side.uaxis and Side.vaxis.
These define the alignment of textures on a face.
-
class
srctools.vmf.
EntityFixup
(fixup: Iterable[FixupValue] = ()) A specialised mapping which keeps track of the variable indexes.
This treats variable names case-insensitively, and optionally allows writing variables with $ signs in front. The case of the first assigned name for each key is preserved.
Additionally, lookups never fail - returning ‘’ instead. Pass in a non-string default or use in to distinguish,.
-
get
(var: str) str -
get
(var: str, default: Union[str, T]) Union[str, T] Get the value of an instance $replace variable.
If not found, the default will be returned (an empty string).
-
copy_values
() List[FixupValue] Generate a list that can be passed to the constructor.
-
setdefault
(var: str) str -
setdefault
() Union[str, ValidKV_T] Return $key, but if not present set it to the default and return that.
-
items
() _EntityFixupItems Iterate over all variable-value pairs.
-
values
() _EntityFixupValues Iterate over all variable values.
-
substitute
() str Substitute the fixup variables into the provided string.
Variables are found based on the defined values, so constructions such as val$varval are valid (with no delimiter indicating the end of variables). Longer matches are preferred. If the name after $ is not found at all, a KeyError is raised, or if default is provided it is substituted.
Any key is valid if defined in the instance, but only a-z, 0-9 and _ is detected for the default functionality.
If allow_invert is enabled, a variable can additionally be specified like !$var to cause it to be inverted when substituted.
-
int
(key: str, def_: Union[int, T] = 0) Union[int, T] Return the value of an integer key.
Equivalent to int(fixup[key]), but with a default value if missing or invalid.
-
float
(key: str, def_: Union[float, T] = 0.0) Union[float, T] Return the value of an integer key.
Equivalent to float(fixup[key]), but with a default value if missing or invalid.
-
-
class
srctools.vmf.
FixupValue
(var: str, value: str, id: int) One $fixup variable with its replacement.
-
class
srctools.vmf.
Output
(out: str,)
targ: Union[Entity, str],
inp: str,
param: Union[str, int, bool, float, VecBase, Vec_tuple, Tuple[float, float, float], Angle, FrozenAngle, Matrix, FrozenMatrix] = '',
delay: float = 0.0,
*,
times: int = -1,
only_once: bool = False,
inst_out: Optional[str] = None,
inst_in: Optional[str] = None,
comma_sep: bool = False, An output from one entity pointing to another.
When parsing, either the post-L4D
0x1B
character can be used, or the previous,
delimiters can be used. For commas, extraneous ones will be treated as part of the parameters.-
SEP
: Final = '\x1b' The character used to separate output values, after L4D. Before then commas (
,
) were used.
-
inst_in
: Optional[str] The local entity we are really triggering in instance inputs (
instance:name;Input
)
-
times
: int The number of times to fire before being deleted.
-1
means forever, Hammer only uses-1
and1
.
-
comma_sep
: bool Use a comma as a separator, instead of the
OUTPUT_SEP
character.
-
property
only_once
: bool Instead of setting
times
, this provides an interface like how Hammer does.
-
classmethod
combine
(first: Output, second: Output) Output Combine two outputs into a merged form.
This is suitable for combining a Trigger and OnTriggered pair into one, or similar values.
-
static
parse_name
(name: str) Tuple[Optional[str], str] Extract the instance name from values of the form:
‘instance:local_name;Command’ This then returns a local_name, command tuple. If not of this form, the first value will be None.
-
-
srctools.vmf.
OUTPUT_SEP
: Final = '\x1b' The character used to separate output values, after L4D. Before then commas (
,
) were used. This is also available asOutput.SEP
.