spawnpoint-studio 0.1.0__py3-none-any.whl

spawnpoint/_data/godot/addons/spawn_point/components/platformer_movement_component.gd

@@ -0,0 +1,204 @@
+class_name PlatformerMovementComponent
+extends Node
+## Side-view running and jumping tuned for good game feel.
+##
+## Includes coyote time (jump shortly after leaving a ledge), jump buffering (press jump shortly
+## before landing), variable jump height (release early for a short hop), stronger gravity when
+## falling, a little hang time at the apex, snappy turning and an optional dash.
+## Reads intent (move_vector, jump requests) from a controller such as PlayerInput or PatrolAI.
+
+const SP_NAME := "PlatformerMovement"
+const SP_HOSTS: Array[String] = ["CharacterBody2D"]
+const SP_REQUIRES: Array[String] = []
+const SP_INTERNAL: Array[String] = ["step_velocity"]
+const SP_CATEGORY := "movement"
+
+## Emitted when a jump starts (ground, coyote or air jump).
+signal jumped
+## Emitted when touching the floor after being airborne. [param impact_speed] is the fall speed.
+signal landed(impact_speed: float)
+## Emitted when a dash starts.
+signal dashed
+
+## Top running speed (px/s).
+@export_range(0.0, 2000.0, 1.0) var max_speed: float = 230.0
+## Ground acceleration toward max speed (px/s²).
+@export_range(0.0, 20000.0, 10.0) var acceleration: float = 2200.0
+## Ground deceleration when no input (px/s²).
+@export_range(0.0, 20000.0, 10.0) var deceleration: float = 2600.0
+## Air acceleration (px/s²). Lower = less air control.
+@export_range(0.0, 20000.0, 10.0) var air_acceleration: float = 1500.0
+## Air deceleration when no input (px/s²).
+@export_range(0.0, 20000.0, 10.0) var air_deceleration: float = 800.0
+## Initial jump speed (px/s). Jump height ≈ jump_velocity² / (2·gravity).
+@export_range(0.0, 3000.0, 1.0) var jump_velocity: float = 620.0
+## Multiplies the project gravity for this entity.
+@export_range(0.0, 5.0, 0.05) var gravity_scale: float = 1.0
+## Extra gravity while falling — makes jumps feel weighty instead of floaty.
+@export_range(1.0, 5.0, 0.05) var fall_gravity_multiplier: float = 1.7
+## Vertical speed is multiplied by this when jump is released while rising (short hop).
+@export_range(0.0, 1.0, 0.05) var jump_cut: float = 0.45
+## Gravity multiplier near the top of a held jump (a little hang time).
+@export_range(0.1, 1.0, 0.05) var apex_gravity_multiplier: float = 0.6
+## Vertical speed below which the apex hang applies (px/s).
+@export_range(0.0, 500.0, 1.0) var apex_threshold: float = 70.0
+## Terminal fall speed (px/s).
+@export_range(50.0, 5000.0, 1.0) var max_fall_speed: float = 900.0
+## Seconds after leaving a ledge during which jumping still works.
+@export_range(0.0, 0.5, 0.01) var coyote_time: float = 0.1
+## Seconds a jump press is remembered before landing.
+@export_range(0.0, 0.5, 0.01) var jump_buffer: float = 0.12
+## Extra jumps in the air (1 = double jump).
+@export_range(0, 5) var air_jumps: int = 0
+## Dash speed (px/s). 0 disables dashing.
+@export_range(0.0, 3000.0, 1.0) var dash_speed: float = 0.0
+## Dash duration in seconds.
+@export_range(0.02, 1.0, 0.01) var dash_duration: float = 0.14
+## Seconds between dashes.
+@export_range(0.0, 5.0, 0.01) var dash_cooldown: float = 0.45
+
+## Intent: x in -1..1 is the run direction (y is ignored).
+var move_vector := Vector2.ZERO
+## Intent: true while the jump button is held (enables full-height jumps).
+var jump_held := false
+## 1 = facing right, -1 = facing left.
+var facing := 1
+
+var _body: CharacterBody2D
+var _coyote_left := 0.0
+var _buffer_left := 0.0
+var _air_jumps_left := 0
+var _rising_from_jump := false
+var _dash_requested := false
+var _dash_left := 0.0
+var _dash_cd := 0.0
+var _dash_dir := 1
+var _control_lock := 0.0
+var _was_on_floor := true
+
+
+func _ready() -> void:
+	_body = get_parent() as CharacterBody2D
+	if _body:
+		_body.motion_mode = CharacterBody2D.MOTION_MODE_GROUNDED
+		_body.floor_snap_length = 6.0
+
+
+## Asks for a jump; it happens as soon as it is allowed (buffered).
+func request_jump() -> void:
+	_buffer_left = jump_buffer if jump_buffer > 0.0 else 0.0001
+
+
+## Asks for a dash in the move / facing direction.
+func request_dash() -> void:
+	_dash_requested = true
+
+
+## Launches the entity upward (e.g. after stomping an enemy). Not cut by releasing jump.
+func bounce(speed: float) -> void:
+	if _body:
+		_body.velocity.y = -absf(speed)
+	_rising_from_jump = false
+
+
+## Pushes the entity; player control is reduced briefly so the push is felt.
+func apply_knockback(impulse: Vector2) -> void:
+	if _body == null:
+		return
+	_body.velocity = Vector2(impulse.x, minf(impulse.y, -absf(impulse.length()) * 0.5))
+	_control_lock = 0.18
+	_dash_left = 0.0
+	_rising_from_jump = false
+
+
+## True while dashing.
+func is_dashing() -> bool:
+	return _dash_left > 0.0
+
+
+func _physics_process(delta: float) -> void:
+	if _body == null:
+		return
+	var v := step_velocity(_body.velocity, delta, _body.is_on_floor())
+	_body.velocity = v
+	_body.move_and_slide()
+	var on_floor := _body.is_on_floor()
+	if on_floor and not _was_on_floor:
+		landed.emit(maxf(v.y, 0.0))
+	_was_on_floor = on_floor
+
+
+## Pure movement step: returns the new velocity. Separated from physics for testing.
+func step_velocity(v: Vector2, delta: float, on_floor: bool) -> Vector2:
+	var gravity: float = ProjectSettings.get_setting("physics/2d/default_gravity", 1600.0) * gravity_scale
+
+	if on_floor:
+		_coyote_left = coyote_time
+		_air_jumps_left = air_jumps
+	else:
+		_coyote_left -= delta
+	_buffer_left -= delta
+	_dash_cd -= delta
+	_control_lock -= delta
+
+	if move_vector.x != 0.0:
+		facing = 1 if move_vector.x > 0.0 else -1
+
+	# Dash: fixed horizontal speed, no gravity.
+	if _dash_requested and dash_speed > 0.0 and _dash_cd <= 0.0 and _dash_left <= 0.0:
+		_dash_left = dash_duration
+		_dash_cd = dash_cooldown + dash_duration
+		_dash_dir = facing
+		dashed.emit()
+	_dash_requested = false
+	if _dash_left > 0.0:
+		_dash_left -= delta
+		if _dash_left <= 0.0:
+			return Vector2(_dash_dir * max_speed, 0.0)
+		return Vector2(_dash_dir * dash_speed, 0.0)
+
+	# Horizontal.
+	var target := clampf(move_vector.x, -1.0, 1.0) * max_speed
+	var accel: float
+	if on_floor:
+		accel = acceleration if absf(target) > 0.01 else deceleration
+	else:
+		accel = air_acceleration if absf(target) > 0.01 else air_deceleration
+	if absf(target) > 0.01 and signf(target) != signf(v.x) and v.x != 0.0:
+		accel *= 1.6  # Snappy turnarounds.
+	if _control_lock > 0.0:
+		accel *= 0.15
+	v.x = move_toward(v.x, target, accel * delta)
+
+	# Jump (buffered, coyote, air jumps).
+	if _buffer_left > 0.0:
+		if on_floor or _coyote_left > 0.0:
+			v.y = _start_jump()
+		elif _air_jumps_left > 0:
+			_air_jumps_left -= 1
+			v.y = _start_jump()
+
+	# Variable jump height.
+	if _rising_from_jump and not jump_held and v.y < 0.0:
+		v.y *= jump_cut
+		_rising_from_jump = false
+	if v.y >= 0.0:
+		_rising_from_jump = false
+
+	# Gravity.
+	if not on_floor or v.y < 0.0:
+		var g := gravity
+		if v.y > 0.0:
+			g *= fall_gravity_multiplier
+		elif absf(v.y) < apex_threshold and jump_held:
+			g *= apex_gravity_multiplier
+		v.y = minf(v.y + g * delta, max_fall_speed)
+	return v
+
+
+func _start_jump() -> float:
+	_buffer_left = 0.0
+	_coyote_left = 0.0
+	_rising_from_jump = true
+	jumped.emit()
+	return -jump_velocity

spawnpoint/_data/godot/addons/spawn_point/components/player_input_component.gd

@@ -0,0 +1,77 @@
+class_name PlayerInputComponent
+extends Node
+## Keyboard/mouse controller for the player. Writes intent into the movement component and
+## pulls weapon triggers. Registers its own input actions, so no project setup is needed.
+##
+## Default keys: move = WASD / arrows, jump = Space / Z / W / Up, dash = Shift / C / K,
+## shoot = X / J / left mouse.
+
+const SP_NAME := "PlayerInput"
+const SP_HOSTS: Array[String] = ["CharacterBody2D"]
+const SP_REQUIRES: Array[String] = []
+const SP_INTERNAL: Array[String] = ["ensure_actions"]
+const SP_CATEGORY := "controller"
+
+const ACTIONS := {
+	&"move_left": [KEY_A, KEY_LEFT],
+	&"move_right": [KEY_D, KEY_RIGHT],
+	&"move_up": [KEY_W, KEY_UP],
+	&"move_down": [KEY_S, KEY_DOWN],
+	&"jump": [KEY_SPACE, KEY_Z, KEY_W, KEY_UP],
+	&"dash": [KEY_SHIFT, KEY_C, KEY_K],
+	&"shoot": [KEY_X, KEY_J, MOUSE_BUTTON_LEFT],
+}
+
+var _entity: Node
+
+
+static func ensure_actions() -> void:
+	for action: StringName in ACTIONS:
+		if InputMap.has_action(action):
+			continue
+		InputMap.add_action(action, 0.2)
+		for code: int in ACTIONS[action]:
+			var ev: InputEvent
+			if action == &"shoot" and code == MOUSE_BUTTON_LEFT:
+				var mb := InputEventMouseButton.new()
+				mb.button_index = MOUSE_BUTTON_LEFT
+				ev = mb
+			else:
+				var k := InputEventKey.new()
+				k.physical_keycode = code
+				ev = k
+			InputMap.action_add_event(action, ev)
+
+
+func _ready() -> void:
+	ensure_actions()
+	_entity = get_parent()
+	# Run before movement and weapons in the same physics frame.
+	process_physics_priority = -10
+
+
+func _physics_process(_delta: float) -> void:
+	if not GameState.is_playing():
+		_clear_intent()
+		return
+	var mv := SP.movement(_entity)
+	if mv:
+		mv.move_vector = Input.get_vector(&"move_left", &"move_right", &"move_up", &"move_down")
+		if Input.is_action_just_pressed(&"dash"):
+			mv.request_dash()
+		if mv is PlatformerMovementComponent:
+			mv.jump_held = Input.is_action_pressed(&"jump")
+			if Input.is_action_just_pressed(&"jump"):
+				mv.request_jump()
+	var weapon := SP.component(_entity, &"Weapon") as WeaponComponent
+	if weapon:
+		weapon.trigger_held = Input.is_action_pressed(&"shoot")
+
+
+func _clear_intent() -> void:
+	var mv := SP.movement(_entity)
+	if mv:
+		mv.move_vector = Vector2.ZERO
+	var weapon := SP.component(_entity, &"Weapon") as WeaponComponent
+	if weapon:
+		weapon.trigger_held = false

spawnpoint/_data/godot/addons/spawn_point/components/projectile_component.gd

@@ -0,0 +1,64 @@
+class_name ProjectileComponent
+extends Node
+## Moves its entity in a straight line; disappears on walls, after its lifetime, or after
+## hitting [member pierce] + 1 targets. Pair with a Hitbox to deal damage.
+
+const SP_NAME := "Projectile"
+const SP_HOSTS: Array[String] = ["Area2D"]
+const SP_REQUIRES: Array[String] = []
+const SP_CATEGORY := "core"
+
+## Emitted when the projectile disappears (wall, lifetime or last hit).
+signal expired
+
+## Speed in px/s.
+@export_range(0.0, 5000.0, 1.0) var speed: float = 620.0
+## Seconds before disappearing.
+@export_range(0.05, 20.0, 0.05) var lifetime: float = 1.4
+## Number of extra targets it passes through.
+@export_range(0, 99) var pierce: int = 0
+
+## Flight direction (set by the Weapon at spawn).
+var direction := Vector2.RIGHT
+
+var _entity: Area2D
+var _age := 0.0
+var _done := false
+
+
+func _ready() -> void:
+	_entity = get_parent() as Area2D
+	if _entity.has_meta(&"sp_direction"):
+		direction = (_entity.get_meta(&"sp_direction") as Vector2).normalized()
+	_entity.body_entered.connect(_on_body_entered)
+	var hitbox := SP.component(_entity, &"Hitbox") as HitboxComponent
+	if hitbox:
+		hitbox.hit.connect(_on_hit)
+
+
+func _physics_process(delta: float) -> void:
+	if _done:
+		return
+	_entity.global_position += direction * speed * delta
+	_age += delta
+	if _age >= lifetime:
+		expire()
+
+
+## Removes the projectile now.
+func expire() -> void:
+	if _done:
+		return
+	_done = true
+	expired.emit()
+	_entity.queue_free()
+
+
+func _on_body_entered(_body: Node) -> void:
+	expire()
+
+
+func _on_hit(_target: Node) -> void:
+	pierce -= 1
+	if pierce < 0:
+		expire()

spawnpoint/_data/godot/addons/spawn_point/components/spawner_component.gd

@@ -0,0 +1,58 @@
+class_name SpawnerComponent
+extends Node
+## Spawns entities at its position on a timer (enemy waves, portals, hazards).
+
+const SP_NAME := "Spawner"
+const SP_HOSTS: Array[String] = []
+const SP_REQUIRES: Array[String] = []
+const SP_CATEGORY := "core"
+const SP_ENTITY_PARAMS: Array[String] = ["entity"]
+
+## Emitted after each spawn with the new node.
+signal spawned(node: Node)
+
+## Entity type to spawn.
+@export var entity: String = ""
+## Seconds between spawns.
+@export_range(0.05, 600.0, 0.05) var interval: float = 3.0
+## Seconds before the first spawn.
+@export_range(0.0, 600.0, 0.05) var start_delay: float = 1.0
+## Do not spawn while this many spawned entities are alive.
+@export_range(1, 500) var max_alive: int = 5
+## Total spawns before stopping (0 = unlimited).
+@export_range(0, 10000) var total: int = 0
+## Random offset radius around the spawner (px).
+@export_range(0.0, 2000.0, 1.0) var radius: float = 0.0
+
+var _timer := 0.0
+var _count := 0
+var _alive: Array[Node] = []
+
+
+func _ready() -> void:
+	_timer = start_delay
+
+
+func _physics_process(delta: float) -> void:
+	if not GameState.is_playing() or (total > 0 and _count >= total):
+		return
+	_timer -= delta
+	if _timer > 0.0:
+		return
+	_timer = interval
+	_alive.assign(_alive.filter(func(n: Node) -> bool: return is_instance_valid(n) and not n.is_queued_for_deletion()))
+	if _alive.size() >= max_alive:
+		return
+	spawn_now()
+
+
+## Spawns one entity immediately. Returns it (or null).
+func spawn_now() -> Node:
+	var origin := (get_parent() as Node2D).global_position
+	var offset := Vector2.from_angle(randf() * TAU) * randf() * radius
+	var n := World.spawn(entity, origin + offset)
+	if n:
+		_count += 1
+		_alive.append(n)
+		spawned.emit(n)
+	return n

spawnpoint/_data/godot/addons/spawn_point/components/stomp_component.gd

@@ -0,0 +1,56 @@
+class_name StompComponent
+extends Area2D
+## Platformer "jump on their head" attack: landing on an enemy from above damages it and
+## bounces this entity up. Grants a moment of invincibility so the enemy's contact damage
+## does not trigger in the same frame.
+
+const SP_NAME := "Stomp"
+const SP_HOSTS: Array[String] = ["CharacterBody2D"]
+const SP_REQUIRES: Array[String] = ["PlatformerMovement"]
+const SP_CATEGORY := "core"
+
+## Emitted after a successful stomp on [param target].
+signal stomped(target: Node)
+
+## Damage dealt by a stomp.
+@export_range(0, 999) var damage: int = 1
+## Upward speed after a stomp (px/s). Holding jump does not add to it.
+@export_range(0.0, 3000.0, 1.0) var bounce_velocity: float = 480.0
+## Stomp area size relative to the entity shape.
+@export_range(0.1, 2.0, 0.05) var size_scale: float = 1.0
+
+var _body: CharacterBody2D
+
+
+func _ready() -> void:
+	_body = SP.entity_of(get_parent()) as CharacterBody2D
+	monitorable = false
+	monitoring = true
+	collision_layer = 0
+	collision_mask = SP.opposing_hurtbox_mask(SP.team_of(_body))
+	# Run before enemy hitboxes so a stomp wins over contact damage.
+	process_physics_priority = -20
+
+
+func _physics_process(_delta: float) -> void:
+	if _body.velocity.y <= 0.0:
+		return
+	var feet := _body.global_position.y + SP.half_size(_body).y
+	for area in get_overlapping_areas():
+		var hb := area as HurtboxComponent
+		if hb == null:
+			continue
+		var target := SP.entity_of(hb) as Node2D
+		if target == null or target == _body:
+			continue
+		# Only counts when our feet are above the target's center.
+		if feet > target.global_position.y + 2.0:
+			continue
+		var my_health := SP.component(_body, &"Health") as HealthComponent
+		if my_health:
+			my_health.grant_invincibility(0.2)
+		hb.take_hit(damage, _body.global_position, 0.0, _body)
+		var mv := SP.component(_body, &"PlatformerMovement") as PlatformerMovementComponent
+		mv.bounce(bounce_velocity)
+		stomped.emit(target)
+		return

spawnpoint/_data/godot/addons/spawn_point/components/top_down_movement_component.gd

@@ -0,0 +1,101 @@
+class_name TopDownMovementComponent
+extends Node
+## Eight-direction movement seen from above, with acceleration, friction and an optional dash.
+## Reads intent (move_vector, dash requests) from a controller such as PlayerInput or ChaseAI.
+
+const SP_NAME := "TopDownMovement"
+const SP_HOSTS: Array[String] = ["CharacterBody2D"]
+const SP_REQUIRES: Array[String] = []
+const SP_INTERNAL: Array[String] = ["step_velocity"]
+const SP_CATEGORY := "movement"
+
+## Emitted when a dash starts.
+signal dashed
+
+## Top speed (px/s).
+@export_range(0.0, 2000.0, 1.0) var max_speed: float = 240.0
+## Acceleration toward the input direction (px/s²).
+@export_range(0.0, 20000.0, 10.0) var acceleration: float = 2400.0
+## Deceleration when there is no input (px/s²).
+@export_range(0.0, 20000.0, 10.0) var friction: float = 2800.0
+## Dash speed (px/s). 0 disables dashing.
+@export_range(0.0, 3000.0, 1.0) var dash_speed: float = 0.0
+## Dash duration in seconds.
+@export_range(0.02, 1.0, 0.01) var dash_duration: float = 0.12
+## Seconds between dashes.
+@export_range(0.0, 5.0, 0.01) var dash_cooldown: float = 0.5
+
+## Intent: desired direction, length 0..1.
+var move_vector := Vector2.ZERO
+## Last non-zero movement direction.
+var facing_dir := Vector2.RIGHT
+## Compatibility with platformer code paths: sign of facing_dir.x.
+var facing := 1
+
+var _body: CharacterBody2D
+var _dash_requested := false
+var _dash_left := 0.0
+var _dash_cd := 0.0
+var _dash_dir := Vector2.RIGHT
+var _control_lock := 0.0
+
+
+func _ready() -> void:
+	_body = get_parent() as CharacterBody2D
+	if _body:
+		_body.motion_mode = CharacterBody2D.MOTION_MODE_FLOATING
+
+
+## Asks for a dash in the movement (or facing) direction.
+func request_dash() -> void:
+	_dash_requested = true
+
+
+## Pushes the entity; control is reduced briefly.
+func apply_knockback(impulse: Vector2) -> void:
+	if _body == null:
+		return
+	_body.velocity = impulse
+	_control_lock = 0.15
+	_dash_left = 0.0
+
+
+## True while dashing.
+func is_dashing() -> bool:
+	return _dash_left > 0.0
+
+
+func _physics_process(delta: float) -> void:
+	if _body == null:
+		return
+	_body.velocity = step_velocity(_body.velocity, delta)
+	_body.move_and_slide()
+
+
+## Pure movement step: returns the new velocity.
+func step_velocity(v: Vector2, delta: float) -> Vector2:
+	_dash_cd -= delta
+	_control_lock -= delta
+	var input := move_vector.limit_length(1.0)
+	if input.length() > 0.1:
+		facing_dir = input.normalized()
+		if absf(facing_dir.x) > 0.1:
+			facing = 1 if facing_dir.x > 0.0 else -1
+
+	if _dash_requested and dash_speed > 0.0 and _dash_cd <= 0.0 and _dash_left <= 0.0:
+		_dash_left = dash_duration
+		_dash_cd = dash_cooldown + dash_duration
+		_dash_dir = facing_dir
+		dashed.emit()
+	_dash_requested = false
+	if _dash_left > 0.0:
+		_dash_left -= delta
+		if _dash_left <= 0.0:
+			return _dash_dir * max_speed
+		return _dash_dir * dash_speed
+
+	var target := input * max_speed
+	var rate := acceleration if input.length() > 0.1 else friction
+	if _control_lock > 0.0:
+		rate *= 0.15
+	return v.move_toward(target, rate * delta)

spawnpoint/_data/godot/addons/spawn_point/components/trigger_zone_component.gd

@@ -0,0 +1,32 @@
+class_name TriggerZoneComponent
+extends Node
+## An invisible-or-visible zone that fires [signal triggered] when an entity of [member group]
+## enters (exit doors, checkpoints, kill zones, tutorial hints).
+
+const SP_NAME := "TriggerZone"
+const SP_HOSTS: Array[String] = ["Area2D"]
+const SP_REQUIRES: Array[String] = []
+const SP_CATEGORY := "core"
+
+## Emitted when a matching body enters.
+signal triggered(body: Node)
+
+## Only bodies in this group trigger the zone ("player", an entity name, or "" for any).
+@export var group: String = "player"
+## Trigger only the first time.
+@export var once := true
+
+var _fired := false
+
+
+func _ready() -> void:
+	(get_parent() as Area2D).body_entered.connect(_on_body_entered)
+
+
+func _on_body_entered(body: Node) -> void:
+	if once and _fired:
+		return
+	if group != "" and not body.is_in_group(StringName(group)):
+		return
+	_fired = true
+	triggered.emit(body)

spawnpoint/_data/godot/addons/spawn_point/components/weapon_component.gd

@@ -0,0 +1,83 @@
+class_name WeaponComponent
+extends Node2D
+## Fires projectile entities. Aim comes from aim_direction (set by Aim or ChaseAI), otherwise
+## from the movement facing. Projectiles inherit the shooter's team.
+
+const SP_NAME := "Weapon"
+const SP_HOSTS: Array[String] = []
+const SP_REQUIRES: Array[String] = []
+const SP_INTERNAL: Array[String] = ["current_direction"]
+const SP_CATEGORY := "core"
+## Parameters that must name an entity in the graph.
+const SP_ENTITY_PARAMS: Array[String] = ["projectile"]
+
+## Emitted every time the weapon fires.
+signal fired
+
+## Entity type spawned as the projectile (must have a Projectile component).
+@export var projectile: String = "Bullet"
+## Shots per second.
+@export_range(0.1, 60.0, 0.1) var fire_rate: float = 6.0
+## Random spread in degrees (total cone width).
+@export_range(0.0, 180.0, 0.5) var spread_deg: float = 4.0
+## Projectiles per shot (shotgun when > 1, spread evenly over spread_deg).
+@export_range(1, 32) var projectile_count: int = 1
+## Spawn distance from the entity center (px).
+@export_range(0.0, 200.0, 1.0) var muzzle_distance: float = 20.0
+## Fire continuously without input (enemies, turrets).
+@export var auto_fire := false
+## Push applied to the shooter opposite to the shot (px/s). 0 = none.
+@export_range(0.0, 2000.0, 1.0) var recoil: float = 0.0
+
+## Intent: true while the trigger is held.
+var trigger_held := false
+## Intent: aim direction (zero = use movement facing).
+var aim_direction := Vector2.ZERO
+
+var _entity: Node2D
+var _cooldown := 0.0
+
+
+func _ready() -> void:
+	_entity = SP.entity_of(get_parent()) as Node2D
+
+
+func _physics_process(delta: float) -> void:
+	_cooldown -= delta
+	if (trigger_held or auto_fire) and _cooldown <= 0.0 and GameState.is_playing():
+		fire()
+
+
+## Fires immediately (ignores the trigger, respects nothing else).
+func fire() -> void:
+	_cooldown = 1.0 / fire_rate
+	var dir := current_direction()
+	var team := SP.team_of(_entity)
+	var n := projectile_count
+	for i in n:
+		var offset := 0.0
+		if n > 1:
+			offset = lerpf(-spread_deg * 0.5, spread_deg * 0.5, float(i) / float(n - 1))
+		else:
+			offset = randf_range(-spread_deg * 0.5, spread_deg * 0.5)
+		var d := dir.rotated(deg_to_rad(offset))
+		var p := World.spawn(projectile, global_position + d * muzzle_distance, {&"sp_team": team, &"sp_direction": d})
+		if p:
+			p.rotation = d.angle()
+	if recoil > 0.0:
+		var mv := SP.movement(_entity)
+		if mv and mv.has_method(&"apply_knockback") and mv is TopDownMovementComponent:
+			mv.apply_knockback(-dir * recoil)
+	fired.emit()
+
+
+## Direction the weapon currently fires in.
+func current_direction() -> Vector2:
+	if aim_direction.length() > 0.01:
+		return aim_direction.normalized()
+	var mv := SP.movement(_entity)
+	if mv is TopDownMovementComponent:
+		return (mv as TopDownMovementComponent).facing_dir
+	if mv:
+		return Vector2(mv.facing, 0)
+	return Vector2.RIGHT