srctools.instancing

Implements support for collapsing instances.

class srctools.instancing.FixupStyle

Bases: Enum

The kind of fixup style to use.

PREFIX = 0: Entities will be named inst_name-ent_name.

SUFFIX = 1: Entities will be named ent_name-inst_name.

NONE = 2: Entities will remain named ent_name.

class srctools.instancing.Instance( name: str, filename: str, pos: Vec, orient: Matrix, fixup_type: FixupStyle = FixupStyle.PREFIX, outputs: Iterable[Output] = (), fixup: Iterable[FixupValue] = (), )

Represents an instance with all the values required to collapse it.

name: str

filename: str

pos: Vec

orient: Matrix

fixup_type: FixupStyle

fixup: EntityFixup

outputs: list[Output]

ent_ids: dict[int, int]

face_ids: dict[int, int]

brush_ids: dict[int, int]

node_ids: dict[int, int]

visgroup_ids: dict[int, int]

recur_count: int

classmethod from_entity(ent: Entity) → Instance: Parse a func_instance entity.

fixup_name(name: str) → str: Apply the name fixup rules to this name.

fixup_key( vmf: VMF, classnames: Container[str], type: ValueTypes, value: str, ) → str

Transform this keyvalue to the new instance’s location and name.

Parameters:

vmf – The rest of the map.
classnames – This is a set of known entity classnames, used to avoid renaming those.
type – The kind of FGD value.
value – The value of the key.

class srctools.instancing.Manifest(name: str, filename: str, id: int, is_toplevel: bool = False)

Additional options set in VMM manifests.

classmethod parse(tree: Keyvalues) → list[Manifest]: Parse a VMM file.

class srctools.instancing.Param(name: str, type: ValueTypes = ValueTypes.STRING, default: str = '')

Configuration for a specific fixup variable.

name: str

type: ValueTypes

default: str

class srctools.instancing.InstanceFile(vmf: VMF)

Represents an instance VMF which has been parsed.

vmf: VMF

params: dict[str, Param]

proxy_inputs: dict[tuple[str, str], Output]: Inputs into the instance. The key is the parts of the instance:name;input string.

proxy_outputs: dict[tuple[str, str], tuple[int, Output]]: Outputs out of the instance. The key is the parts of the instance:name;output string. The value is the ID of the entity to add the output to.

proxy_pos: Vec: If instructed to add in a proxy later, this is the local pos to place it.

parse() → None: Parse func_instance_params and io_proxies in the map.

srctools.instancing.get_inst_locs(map_filename: Path) → FileSystemChain

Given a map filename, find sdk_content and produce the lookup locations.

The chained filesystem will first look relative to the map, then in sdk_content/maps/ if that’s a parent directory.

srctools.instancing.collapse_all( vmf: VMF, fsys: FileSystem, recur_limit: int = 100, ) → None

Searches for func_instance in the map, then collapses them.

Parameters:

vmf – The map to analyse.
fsys – The filesystem is used to find the relevant instances.
recur_limit – The recursion limit indicates how many instances can be contained in another - if it’s exceeded they’re left in the map.

srctools.instancing.collapse_one( vmf: VMF, inst: Instance, file: InstanceFile, *, visgroup: bool | VisGroup = False, engine_cache: MutableMapping[str, EntityDef] = ..., fgd: FGD | None = None, ) → None

Collapse a single instance into the map.

The visgroup parameter controls how visgroups are handled:

If False, visgroups are stripped.
If True, the original visgroups will be kept.
If set to a specific visgroup, all ents and brushes will be added to it, with any existing visgroups in the instance added as a child.

Parameters:

engine_cache – This is a dict used to cache parsed FGD data for remapping. If multiple instances are being collapsed, create an empty dict and pass it in to every call to allow reusing data.
fgd –

deprecated:

old method of passing in a FGD database.