Game feel skill for AI agents

npx -y summer-engine@latest skills install game-feel --agent claude-code

summer_get_scene_tree
summer_inspect_node "./World/Enemy"   # the body that gets hit
summer_inspect_node "./World/Player/Camera3D"   # the camera to shake

World/
  Enemy (CharacterBody3D)
    Mesh (MeshInstance3D)        # the visible body
    HitFlash (Node)              # holds the script, no transform

summer_add_node(scenePath="res://levels/world.tscn", parent="./World/Enemy", type="Node", name="HitFlash")
summer_set_prop(scenePath="res://levels/world.tscn", path="./World/Enemy/HitFlash", key="script", value="res://scripts/vfx/hit_flash.gd")

class_name HitFlash
extends Node

@export var mesh: MeshInstance3D
@export var flash_color: Color = Color(1.0, 1.0, 1.0)
@export var duration: float = 0.08

var _orig_albedo: Color
var _flash_mat: StandardMaterial3D
var _tween: Tween

func _ready() -> void:
    if mesh == null:
        push_warning("HitFlash: mesh export not assigned")
        return
    # Build a dedicated override material once. Cloning the surface material
    # would also work, but a fresh StandardMaterial3D is simpler and free.
    _flash_mat = StandardMaterial3D.new()
    _flash_mat.albedo_color = flash_color
    _flash_mat.emission_enabled = true
    _flash_mat.emission = flash_color
    _flash_mat.emission_energy_multiplier = 2.0
    _orig_albedo = _flash_mat.albedo_color
    mesh.material_override = null  # leave original mesh material in place

func flash() -> void:
    if mesh == null:
        return
    if _tween and _tween.is_valid():
        _tween.kill()  # restart cleanly on rapid re-hits
    mesh.material_override = _flash_mat
    _flash_mat.albedo_color = flash_color
    _tween = create_tween()
    _tween.tween_interval(duration)
    _tween.tween_callback(func() -> void: mesh.material_override = null)

summer_inspect_node(path="./World/Player/Camera3D")
summer_set_prop(scenePath="res://levels/world.tscn", path="./World/Player/Camera3D", key="script", value="res://scripts/vfx/camera_shake.gd")

class_name CameraShake
extends Camera3D

@export var trauma_decay: float = 3.0       # how fast trauma bleeds off (per second)
@export var max_shake_angle_deg: float = 2.5 # max pitch at trauma = 1.0
@export var yaw_factor: float = 0.5          # less yaw than pitch (eye anatomy)

var _trauma: float = 0.0
var _shake_offset: Vector3 = Vector3.ZERO

func _ready() -> void:
    # Node has no `groups` property, so there is nothing to set from the outside.
    # Joining the group here is how any actor finds this camera later.
    add_to_group(&"player_camera")

func add_trauma(amount: float) -> void:
    _trauma = clamp(_trauma + amount, 0.0, 1.0)

func _process(delta: float) -> void:
    # Always undo last frame's offset BEFORE deciding the next.
    # Without this, rotation drifts every frame trauma is non-zero.
    if _shake_offset != Vector3.ZERO:
        rotation -= _shake_offset
        _shake_offset = Vector3.ZERO

    if _trauma <= 0.0:
        return

    var shake := _trauma * _trauma   # quadratic — small hits barely shake
    var max_angle := deg_to_rad(max_shake_angle_deg) * shake

    _shake_offset = Vector3(
        randf_range(-max_angle, max_angle),
        randf_range(-max_angle, max_angle) * yaw_factor,
        0.0
    )
    rotation += _shake_offset
    _trauma = max(0.0, _trauma - trauma_decay * delta)

$Camera3D.add_trauma(0.3)   # light hit (parry, glancing blow)
$Camera3D.add_trauma(0.5)   # standard combat hit
$Camera3D.add_trauma(0.8)   # heavy / explosion

extends Node

# Bus name -> duck weight (1.0 = full duck, 0.0 = never duck this bus).
# "SFX" / "UI" / "Voice" should NOT be ducked — those are the buses you want
# to punch through. Adjust to match your project's default_bus_layout.tres.
const BUS_WEIGHTS := {
    &"Music":     0.9,
    &"Ambient":   0.7,
    &"Announcer": 0.5,
}

# How loud the bus is "when not ducked", captured once. NEVER overwrite —
# this is the user's preference and mixer baseline.
var _initial_volumes: Dictionary = {}
var _tween: Tween

func _ready() -> void:
    for bus_name in BUS_WEIGHTS.keys():
        var idx := AudioServer.get_bus_index(bus_name)
        if idx == -1:
            push_warning("AudioDucker: bus '%s' not found in bus layout" % bus_name)
            continue
        _initial_volumes[bus_name] = AudioServer.get_bus_volume_db(idx)

# amount: 0.0–1.0 (0.5 = noticeable, 1.0 = near-silence on weighted buses)
# duration: total duck-and-restore time, seconds. 0.4–0.6 feels right for hits.
func duck(amount: float, duration: float = 0.5) -> void:
    if _initial_volumes.is_empty():
        return
    if _tween and _tween.is_valid():
        _tween.kill()
    _tween = create_tween().set_parallel(true)

    var attack := duration * 0.15  # fast duck-down, slow restore
    var release := duration * 0.85

    for bus_name in _initial_volumes.keys():
        var idx := AudioServer.get_bus_index(bus_name)
        if idx == -1:
            continue
        var base_db: float = _initial_volumes[bus_name]
        var weight: float = BUS_WEIGHTS.get(bus_name, 0.0)
        # Convert "amount" (0–1) into a dB drop. -24 dB at amount=1, weight=1
        # is "almost gone" without being absolute silence.
        var drop_db := -24.0 * amount * weight
        var target_db := base_db + drop_db

        # AudioServer exposes bus volume through a method, not an animatable
        # property, so tween_method is the only form that works here.
        # `tween_property(AudioServer, "bus_volume_db", ...)` errors at runtime.
        _tween.tween_method(_set_bus_db.bind(idx), base_db, target_db, attack)\
            .set_trans(Tween.TRANS_QUAD).set_ease(Tween.EASE_OUT)
        _tween.tween_method(_set_bus_db.bind(idx), target_db, base_db, release)\
            .set_trans(Tween.TRANS_QUAD).set_ease(Tween.EASE_IN)\
            .set_delay(attack)

func _set_bus_db(idx: int, db: float) -> void:
    AudioServer.set_bus_volume_db(idx, db)

summer_project_setting(...)   # autoload/AudioDucker = "*res://scripts/vfx/audio_ducker.gd"

AudioDucker.duck(0.5, 0.4)   # standard hit
AudioDucker.duck(0.8, 0.6)   # heavy / boss hit
AudioDucker.duck(1.0, 1.2)   # cinematic — explosion or boss intro

# scripts/enemy.gd (or wherever you handle damage on the body that got hit)
extends CharacterBody3D

signal damaged(amount: float)

@onready var _hit_flash: HitFlash = $HitFlash
@onready var _player_camera: CameraShake = get_tree().get_first_node_in_group("player_camera")

func take_damage(amount: float) -> void:
    # ... your existing health subtract / death check ...
    damaged.emit(amount)
    _on_damaged(amount)

func _on_damaged(amount: float) -> void:
    # 1. Hit flash on this body.
    _hit_flash.flash()
    # 2. Camera shake on the player's camera, scaled by hit weight.
    # clampf(), not clamp(): clamp() returns Variant, and inferring a variable from
    # a Variant is an error under Godot's default warning settings.
    var trauma := clampf(0.2 + amount * 0.05, 0.2, 0.9)
    if _player_camera:
        _player_camera.add_trauma(trauma)
    # 3. Audio duck, scaled by hit weight.
    var duck_amount := clampf(0.3 + amount * 0.04, 0.3, 1.0)
    AudioDucker.duck(duck_amount, 0.45)

summer_connect_signal(scenePath="res://levels/world.tscn", emitter="./World/Enemy", signal="damaged", receiver="./World/Enemy/HitFlash", method="flash")

summer_save_scene(scenePath="res://levels/world.tscn")
summer_get_script_errors(path="res://scripts/vfx/hit_flash.gd")   # repeat for each of the three scripts
summer_play
# user reproduces a hit
summer_get_debugger_errors        # runtime errors from the tweens / bus lookups
summer_stop