srctools.instancing

Implements support for collapsing instances.

class srctools.instancing.FixupStyle(
value,
names=None,
*,
module=None,
qualname=None,
type=None,
start=1,
boundary=None,
)

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.

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.

class srctools.instancing.InstanceFile(vmf: VMF)

Represents an instance VMF which has been parsed.

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] = srctools.EmptyMapping,
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.