Break out ambient_generic spawnflags into keyvalues

This makes them less confusing, and also allows setting them with $fixup variables.
See #260.

CHANGELOG.md

@@ -7,6 +7,7 @@
 * Added `comp_vactube_sensor`, which allows detecting the presence of vactube objects.
 * Allow configuring various shadow/fast reflection options for vactube object ents.
 * Boolean keyvalues (yes/no) can now be set to `!$var`, to invert the value of the variable. 
+* Added three keyvalues to `ambient_generic`, giving a more user friendly interface to the confusing spawnflags. This also allows them to be configured via fixup values easily.
 * Propcombine will now preserve prop fade distances, by calculating a new distance which encloses the original fade spheres.
 * Allow comp_entity_finder to rotate the target in addition to teleporting.
 * Fix various incorrect usages of the FGD `frustum()` helper.

fgd/point/ambient/ambient_generic.fgd

@@ -23,13 +23,40 @@
 
 	sourceentityname(target_destination) : "Source Entity" : : "If an entity is specified, sound will come from this named entity instead of the location of ambient_generic."
 
+	haddons_enabled[engine](integer) : "Start Enabled" : -1
+	haddons_enabled[+srctools](choices) : "[HA] Start Enabled" : -1 : "If set, overrides the 'Start Silent' spawnflag. " +
+		"This allows this value to be easily controlled by $fixup values." = [
+		-1: "Use Spawnflag"
+		0: "[0] Start Silent"
+		1: "[1] Start Playing"
+	]
+
+	haddons_infrange[engine](integer) : "Infinite Range" : -1
+	haddons_infrange[+srctools](choices) : "[HA] Infinite Range" : -1 : "If set, overrides the 'Infinite Range' spawnflag. " +
+		"This allows this value to be easily controlled by $fixup values. " +
+		"Note that if a soundscript is used, that overrides this value." = [
+		-1: "Use Spawnflag"
+		0: "[0] Limited Range"
+		1: "[1] Infinite Range"
+	]
+
+	haddons_mode[engine](integer) : "Looping Mode" : -1
+	haddons_mode[+srctools](choices) : "[HA] Looping Mode" : -1 : "If set, overrides the 'Is NOT Looped' spawnflag. " +
+		"This option controls how the entity controls the output, not whether the sound actually loops. " +
+		"If oneshot, PlaySound starts the sound afresh and StopSound does nothing, " +
+		"while in looping mode PlaySound requires it to already be stopped." =  [
+		-1: "Use Spawnflag"
+		0: "[0] Oneshot Sound"
+		1: "[1] Looping Sound"
+	]
+
 	soundflags[engine](integer) : "Sound Flasg" : 0
 	soundflags[MBase](choices) : "Sound Flags" : 0 : "Additional options for your sound." =
 	[
 		0: "None"
-		128: "[128] Pause when game is paused"
-		256: "[256] Ignore phonemes (no lip-syncing)"
-		1024: "[1024] Don't overwrite existing sound on channel (untested)"
+		128: "Pause when game is paused"
+		256: "Ignore phonemes (no lip-syncing)"
+		1024: "Don't overwrite existing sound on channel (untested)"
 
 		384: "Pause and ignore phonemes"
 		1280: "Ignore phonemes and don't overwrite"

src/hammeraddons/bsp_transform/__init__.py

@@ -13,7 +13,7 @@
 from srctools.packlist import PackList
 
 from hammeraddons.bsp_transform.common import (
-    check_control_enabled,
+    check_control_enabled, ent_description,
     parse_numeric_specifier, NumericSpecifier, NumericOp
 )
 
@@ -24,7 +24,7 @@
     'Context', 'trans', 'run_transformations',
     'TransFunc', 'TRANSFORMS',
     # Utils:
-    'check_control_enabled',
+    'check_control_enabled', 'ent_description',
     'parse_numeric_specifier', 'NumericOp', 'NumericSpecifier',
 ]
 

src/hammeraddons/bsp_transform/common.py

@@ -77,6 +77,17 @@ def check_control_enabled(ent: Entity) -> bool:
         return conv_bool(ent['ctrl_value'], True)
 
 
+def ent_description(ent: Entity) -> str:
+    """Return an identifiable description for an entity."""
+    name = ent['targetname']
+    classname = ent['classname']
+    pos = ent['origin']
+    if name:
+        return f'"{name}" {classname} @ ({pos})'
+    else:
+        return f'{classname} @ ({pos})'
+
+
 @final
 @attrs.frozen
 class RelayOut:

transforms/fgd_tweaks/ambient_generic.py

@@ -0,0 +1,57 @@
+"""Allow ambient_generic's confusing spawnflags to be set via keyvalues instead."""
+from typing import Final
+
+from hammeraddons.bsp_transform import Context, trans, ent_description
+from srctools import conv_int, logger
+
+
+LOGGER = logger.get_logger(__name__)
+
+
+FLAG_INFINITE: Final = 1
+FLAG_START_SILENT: Final = 16
+FLAG_NOT_LOOPED: Final = 32
+
+
+@trans('FGD - ambient_generic keyvalues')
+def ambient_generic_kvs(ctx: Context) -> None:
+    """Allow ambient_generic's confusing spawnflags to be set via keyvalues instead.
+
+    This also allows them to be easily set from $fixup values.
+    Importantly this runs after inv_booleans, so it doesn't need to handle that.
+    """
+    for ent in ctx.vmf.by_class['ambient_generic']:
+        flags = conv_int(ent['spawnflags'])
+
+        # These are inverted.
+        for name, pretty, flag in [
+            ('haddons_enabled', 'Enabled', FLAG_START_SILENT),
+            ('haddons_mode', 'Mode', FLAG_NOT_LOOPED),
+        ]:
+            value = conv_int(ent[name])
+            if value == -1:
+                pass  # Keep spawnflag
+            elif value == 0:
+                flags |= flag
+            elif value == 1:
+                flags &= ~flag
+            else:
+                LOGGER.warning(
+                    '{} value "{}" is invalid for {}: must be -1, 0 or 1!',
+                    pretty, ent[name], ent_description(ent),
+                )
+
+        # Non-inverted
+        value = conv_int(ent['haddons_infrange'])
+        if value == -1:
+            pass  # Keep spawnflag
+        elif value == 0:
+            flags &= ~FLAG_INFINITE
+        elif value == 1:
+            flags |= FLAG_INFINITE
+        else:
+            LOGGER.warning(
+                '{} value "{}" is invalid for {}: must be -1, 0 or 1!',
+                'Infinite Range', ent['haddons_infrange'], ent_description(ent),
+            )
+        ent['spawnflags'] = flags