playtest-patterns

Playtest Patterns

Death Heatmap Collection

# Collect and visualize death positions as a heatmap overlay
class_name DeathHeatmap extends Node2D
var _death_positions: Dictionary = {}  # Vector2i -> int (count)

@export var cell_size: int = 16  # Group deaths by cell size (pixels or world units)
@export var max_heat: int = 10   # Deaths at or above this = max color intensity
@export var heat_color_cold: Color = Color(0, 0, 1, 0.3)   # Blue = few deaths
@export var heat_color_hot: Color = Color(1, 0, 0, 0.7)    # Red = many deaths

func record_death(world_position: Vector2) -> void:
    var cell := Vector2i(int(world_position.x / cell_size), int(world_position.y / cell_size))
    _death_positions[cell] = _death_positions.get(cell, 0) + 1
    queue_redraw()
    _save_to_disk()  # Persist across sessions

func _draw() -> void:
    for cell in _death_positions:
        var count: int = _death_positions[cell]
        var heat := clampf(float(count) / float(max_heat), 0.0, 1.0)
        var color := heat_color_cold.lerp(heat_color_hot, heat)
        var rect := Rect2(
            Vector2(cell) * cell_size,
            Vector2(cell_size, cell_size)
        )
        draw_rect(rect, color)

func _save_to_disk() -> void:
    var file := FileAccess.open("user://death_heatmap.json", FileAccess.WRITE)
    if file:
        var serialized := {}
        for cell in _death_positions:
            serialized["%d,%d" % [cell.x, cell.y]] = _death_positions[cell]
        file.store_string(JSON.stringify(serialized))

func load_from_disk() -> void:
    var file := FileAccess.open("user://death_heatmap.json", FileAccess.READ)
    if not file:
        return
    var parsed := JSON.parse_string(file.get_as_text())
    if parsed is Dictionary:
        for key in parsed:
            var parts := key.split(",")
            var cell := Vector2i(int(parts[0]), int(parts[1]))
            _death_positions[cell] = int(parsed[key])

Analytics Event Schema

# Structured analytics events for funnel and behavior analysis
class_name GameAnalytics extends Node
const ANALYTICS_FILE := "user://analytics_session.jsonl"  # JSON Lines format

var _session_id: String
var _session_start: float

func _ready() -> void:
    _session_id = _generate_session_id()
    _session_start = Time.get_unix_time_from_system()
    _log_event("session_start", {})

func _generate_session_id() -> String:
    return "%d_%d" % [Time.get_unix_time_from_system(), randi()]

func _log_event(event_type: String, data: Dictionary) -> void:
    var event := {
        "session_id": _session_id,
        "timestamp": Time.get_unix_time_from_system(),
        "elapsed": Time.get_unix_time_from_system() - _session_start,
        "event": event_type,
        "data": data
    }
    var file := FileAccess.open(ANALYTICS_FILE, FileAccess.READ_WRITE)
    if not file:
        file = FileAccess.open(ANALYTICS_FILE, FileAccess.WRITE)
    if file:
        file.seek_end()
        file.store_line(JSON.stringify(event))

# Specific event types
func log_player_death(position: Vector3, cause: StringName, level: StringName) -> void:
    _log_event("player_death", {
        "position": {"x": position.x, "y": position.y, "z": position.z},
        "cause": cause,
        "level": level,
    })

func log_level_complete(level: StringName, time_seconds: float, deaths: int) -> void:
    _log_event("level_complete", {
        "level": level,
        "time": time_seconds,
        "deaths": deaths,
    })

func log_mechanic_used(mechanic: StringName, context: StringName) -> void:
    _log_event("mechanic_used", {"mechanic": mechanic, "context": context})

func log_checkpoint_reached(checkpoint_id: StringName) -> void:
    _log_event("checkpoint", {"id": checkpoint_id})

func log_quit(reason: StringName = &"unknown") -> void:
    _log_event("session_end", {
        "reason": reason,
        "total_time": Time.get_unix_time_from_system() - _session_start,
    })