ravensight-playtest 0.5.2 → 0.7.0

package/templates/godot-2d/export_presets.cfg

@@ -0,0 +1,27 @@
+[preset.0]
+
+name="Web"
+platform="Web"
+runnable=true
+export_filter="all_resources"
+include_filter="ravensight_key.release.cfg"
+exclude_filter="ravensight_key.cfg,tools/*,DESIGN.md"
+export_path="build/web/index.html"
+
+[preset.0.options]
+
+html/export_icon=true
+
+[preset.1]
+
+name="Desktop"
+platform="Linux"
+runnable=false
+export_filter="all_resources"
+include_filter="ravensight_key.release.cfg"
+exclude_filter="ravensight_key.cfg,tools/*,DESIGN.md"
+export_path="build/desktop/game.x86_64"
+
+[preset.1.options]
+
+binary_format/embed_pck=true

package/templates/godot-2d/gitignore

@@ -0,0 +1,10 @@
+.godot/
+.ravensight/brief.local.json
+.ravensight/jobs/
+.ravensight/create.json
+.DS_Store
+/build/
+export_credentials.cfg
+# The development key stays on this machine, and the release key is written at build time.
+ravensight_key.cfg
+ravensight_key.release.cfg

package/templates/godot-2d/project.godot

@@ -0,0 +1,58 @@
+; Engine configuration file.
+config_version=5
+
+[application]
+
+config/name="__GAME_NAME__"
+config/description="A placeholder prototype made with ravensight-playtest create."
+config/version="0.1.0"
+run/main_scene="res://scenes/main.tscn"
+config/features=PackedStringArray("4.3", "GL Compatibility")
+boot_splash/show_image=false
+
+[autoload]
+
+GameConfig="*res://scripts/autoload/game_config.gd"
+Ravensight="*res://addons/ravensight/Ravensight.gd"
+Telemetry="*res://scripts/autoload/telemetry.gd"
+GameState="*res://scripts/autoload/game_state.gd"
+
+[display]
+
+window/size/viewport_width=640
+window/size/viewport_height=384
+window/size/window_width_override=1280
+window/size/window_height_override=768
+window/stretch/mode="canvas_items"
+window/stretch/aspect="keep"
+
+[input]
+
+move_left={
+"deadzone": 0.25,
+"events": [Object(InputEventKey,"physical_keycode":65), Object(InputEventKey,"physical_keycode":4194319), Object(InputEventJoypadMotion,"device":-1,"axis":0,"axis_value":-1.0)]
+}
+move_right={
+"deadzone": 0.25,
+"events": [Object(InputEventKey,"physical_keycode":68), Object(InputEventKey,"physical_keycode":4194321), Object(InputEventJoypadMotion,"device":-1,"axis":0,"axis_value":1.0)]
+}
+move_up={
+"deadzone": 0.25,
+"events": [Object(InputEventKey,"physical_keycode":87), Object(InputEventKey,"physical_keycode":4194320), Object(InputEventJoypadMotion,"device":-1,"axis":1,"axis_value":-1.0)]
+}
+move_down={
+"deadzone": 0.25,
+"events": [Object(InputEventKey,"physical_keycode":83), Object(InputEventKey,"physical_keycode":4194322), Object(InputEventJoypadMotion,"device":-1,"axis":1,"axis_value":1.0)]
+}
+action={
+"deadzone": 0.5,
+"events": [Object(InputEventKey,"physical_keycode":32), Object(InputEventKey,"physical_keycode":69), Object(InputEventJoypadButton,"device":-1,"button_index":0)]
+}
+pause={
+"deadzone": 0.5,
+"events": [Object(InputEventKey,"physical_keycode":4194305), Object(InputEventJoypadButton,"device":-1,"button_index":6)]
+}
+
+[rendering]
+
+renderer/rendering_method="gl_compatibility"

package/templates/godot-2d/scenes/main.tscn

@@ -0,0 +1,67 @@
+[gd_scene load_steps=4 format=3]
+
+[ext_resource type="Script" path="res://scripts/main.gd" id="1"]
+[ext_resource type="Script" path="res://scripts/player.gd" id="2"]
+[ext_resource type="Script" path="res://scripts/state_hook.gd" id="3"]
+
+[node name="Main" type="Node2D"]
+script = ExtResource("1")
+
+[node name="Ground" type="ColorRect" parent="."]
+offset_right = 640.0
+offset_bottom = 384.0
+color = Color(0.1, 0.12, 0.16, 1)
+
+[node name="Player" type="Node2D" parent="."]
+position = Vector2(320, 192)
+script = ExtResource("2")
+
+[node name="Shape" type="Polygon2D" parent="Player"]
+color = Color(0.95, 0.75, 0.3, 1)
+polygon = PackedVector2Array(-10, -10, 10, -10, 10, 10, -10, 10)
+
+[node name="StateHook" type="Node" parent="."]
+script = ExtResource("3")
+player_path = NodePath("../Player")
+
+[node name="Interface" type="CanvasLayer" parent="."]
+
+[node name="Hud" type="Label" parent="Interface"]
+offset_left = 8.0
+offset_top = 6.0
+offset_right = 632.0
+offset_bottom = 30.0
+text = ""
+
+[node name="Settings" type="Control" parent="Interface"]
+layout_mode = 3
+anchors_preset = 15
+anchor_right = 1.0
+anchor_bottom = 1.0
+
+[node name="Panel" type="PanelContainer" parent="Interface/Settings"]
+layout_mode = 1
+anchors_preset = 8
+anchor_left = 0.5
+anchor_top = 0.5
+anchor_right = 0.5
+anchor_bottom = 0.5
+offset_left = -160.0
+offset_top = -60.0
+offset_right = 160.0
+offset_bottom = 60.0
+
+[node name="Rows" type="VBoxContainer" parent="Interface/Settings/Panel"]
+layout_mode = 2
+
+[node name="Title" type="Label" parent="Interface/Settings/Panel/Rows"]
+layout_mode = 2
+text = "Settings"
+
+[node name="Analytics" type="CheckBox" parent="Interface/Settings/Panel/Rows"]
+layout_mode = 2
+text = "Share anonymous analytics"
+
+[node name="Hint" type="Label" parent="Interface/Settings/Panel/Rows"]
+layout_mode = 2
+text = "Esc to go back"

package/templates/godot-2d/scripts/autoload/game_config.gd

@@ -0,0 +1,83 @@
+extends Node
+## Runs before the Ravensight autoload and hands it this build's key, so the key is
+## never typed into a script or committed.
+##
+## Where the key comes from, first match wins:
+##   1. --ravensight-key-file=<path> after -- on the command line
+##   2. the RAVENSIGHT_INGEST_KEY environment variable
+##   3. res://ravensight_key.release.cfg, in an exported build only
+##   4. res://ravensight_key.cfg, the development key on this machine
+## --no-key skips all four. Both files are ignored by git. With no key the SDK is
+## inert and the game plays exactly the same.
+
+const GAME_VERSION := "0.1.0"
+const DEVELOPMENT_KEY := "res://ravensight_key.cfg"
+const RELEASE_KEY := "res://ravensight_key.release.cfg"
+
+## Which of the four answered: "argument", "environment", "release", "development" or "none".
+var key_source := "none"
+
+func _ready() -> void:
+	var found := find_key(_user_args(), OS.has_feature("editor"))
+	key_source = String(found["source"])
+	if not String(found["key"]).is_empty():
+		Ravensight.ingest_key = String(found["key"])
+	if not String(found["api_url"]).is_empty():
+		Ravensight.api_url = String(found["api_url"])
+	Ravensight.optional = true
+	Ravensight.game_version = GAME_VERSION
+	Ravensight.distribution = _build_label()
+
+## The key this run should use, and what it came from. No side effects, so a test
+## can call it.
+func find_key(args: Dictionary, in_editor: bool) -> Dictionary:
+	var none := {"key": "", "api_url": "", "source": "none"}
+	if args.has("no-key"):
+		return none
+	if args.has("ravensight-key-file"):
+		var from_file := _read_key(String(args["ravensight-key-file"]))
+		if not String(from_file["key"]).is_empty():
+			from_file["source"] = "argument"
+			return from_file
+	var from_environment := OS.get_environment("RAVENSIGHT_INGEST_KEY").strip_edges()
+	if not from_environment.is_empty():
+		return {"key": from_environment, "api_url": OS.get_environment("RAVENSIGHT_API_URL").strip_edges(), "source": "environment"}
+	if not in_editor:
+		var release := _read_key(RELEASE_KEY)
+		if not String(release["key"]).is_empty():
+			release["source"] = "release"
+			return release
+	var development := _read_key(DEVELOPMENT_KEY)
+	if not String(development["key"]).is_empty():
+		development["source"] = "development"
+		return development
+	return none
+
+func _read_key(path: String) -> Dictionary:
+	var answer := {"key": "", "api_url": "", "source": "none"}
+	if not FileAccess.file_exists(path):
+		return answer
+	var file := ConfigFile.new()
+	if file.load(path) != OK:
+		return answer
+	answer["key"] = String(file.get_value("ravensight", "ingest_key", "")).strip_edges()
+	answer["api_url"] = String(file.get_value("ravensight", "api_url", "")).strip_edges()
+	return answer
+
+func _user_args() -> Dictionary:
+	var out := {}
+	for raw in OS.get_cmdline_user_args():
+		var text := String(raw).trim_prefix("--")
+		var split := text.find("=")
+		if split >= 0:
+			out[text.substr(0, split)] = text.substr(split + 1)
+		else:
+			out[text] = "true"
+	return out
+
+func _build_label() -> String:
+	if OS.has_feature("web"):
+		return "web"
+	if OS.has_feature("editor"):
+		return "editor"
+	return "native-" + OS.get_name().to_lower()

package/templates/godot-2d/scripts/autoload/game_state.gd

@@ -0,0 +1,44 @@
+extends Node
+## What the game is, in numbers. Nothing here draws anything. A persona reads this
+## through scripts/state_hook.gd, and the playable check reads core_loops_completed.
+
+## A milestone calls complete_core_loop() once for each pass of the game's core loop.
+signal core_loop_completed(total: int)
+
+var score := 0
+var level := 1
+var deaths := 0
+var core_loops_completed := 0
+var started := false
+
+## The game started playing. Reported once a run.
+func start_game() -> void:
+	if started:
+		return
+	started = true
+	Telemetry.track("game_play_started", {"level": "level_%d" % level}, "level_start")
+
+## One whole pass of the core loop, which is what "playable" means here.
+func complete_core_loop() -> void:
+	core_loops_completed += 1
+	Telemetry.track("core_loop_completed", {"level": "level_%d" % level, "total": core_loops_completed}, "level_complete")
+	# The moment worth not losing if the player closes the game now.
+	Ravensight.flush()
+	core_loop_completed.emit(core_loops_completed)
+
+func add_score(amount: int) -> void:
+	score += amount
+
+func record_death() -> void:
+	deaths += 1
+	Telemetry.track("player_died", {"level": "level_%d" % level, "deaths": deaths}, "death")
+
+## Plain values only, so it can cross to a playtest as JSON.
+func snapshot() -> Dictionary:
+	return {
+		"started": started,
+		"score": score,
+		"level": level,
+		"deaths": deaths,
+		"core_loops_completed": core_loops_completed,
+	}

package/templates/godot-2d/scripts/autoload/telemetry.gd

@@ -0,0 +1,37 @@
+extends Node
+## Every gameplay event goes through track(), which always says what the event
+## means. Ravensight reads a level start, a level completion or a death from the
+## reserved rs_kind property first, and only guesses from the event's name when it
+## is missing. A natural name such as "room_restarted" or "run_finished" would
+## otherwise be read as something it is not, so nothing here leaves that to chance.
+
+const KINDS := ["level_start", "level_complete", "death", "none"]
+
+## The last event this run asked to send, name and data, for a test to read. Set
+## whether or not the SDK has a key.
+var last_event := {}
+
+## Queue an event. `kind` is one of KINDS. Anything else is sent as "none", with a
+## warning, because a wrong kind would move the game's funnel.
+func track(event_name: String, data: Dictionary = {}, kind: String = "none") -> void:
+	var prepared := prepare(data, kind)
+	last_event = {"name": event_name, "data": prepared}
+	Ravensight.track_event(event_name, prepared)
+
+## The event's data as it will be sent.
+func prepare(data: Dictionary, kind: String) -> Dictionary:
+	var out := data.duplicate()
+	if KINDS.has(kind):
+		out["rs_kind"] = kind
+	else:
+		push_warning("Telemetry: unknown kind %s, sent as none" % kind)
+		out["rs_kind"] = "none"
+	return out
+
+## The player's own choice: the settings overlay calls this. The SDK saves it and
+## it holds on every later run. False stops all analytics, including what is queued.
+func set_analytics_enabled(value: bool) -> void:
+	Ravensight.set_tracking_enabled(value)
+
+func analytics_enabled() -> bool:
+	return not FileAccess.file_exists(Ravensight.OPTOUT_PATH)

package/templates/godot-2d/scripts/main.gd

@@ -0,0 +1,32 @@
+extends Node2D
+## The one scene the scaffold starts on. Milestones build the game here.
+
+@onready var hud: Label = $Interface/Hud
+@onready var settings: Control = $Interface/Settings
+@onready var analytics: CheckBox = $Interface/Settings/Panel/Rows/Analytics
+
+func _ready() -> void:
+	process_mode = Node.PROCESS_MODE_ALWAYS
+	$Player.process_mode = Node.PROCESS_MODE_PAUSABLE
+	settings.visible = false
+	analytics.button_pressed = Telemetry.analytics_enabled()
+	analytics.toggled.connect(Telemetry.set_analytics_enabled)
+	GameState.start_game()
+	_refresh()
+
+func _unhandled_input(event: InputEvent) -> void:
+	if event.is_action_pressed("pause"):
+		_toggle_settings()
+		get_viewport().set_input_as_handled()
+
+func _process(_delta: float) -> void:
+	_refresh()
+
+func _toggle_settings() -> void:
+	settings.visible = not settings.visible
+	get_tree().paused = settings.visible
+	if settings.visible:
+		analytics.grab_focus()
+
+func _refresh() -> void:
+	hud.text = "Score %d  Loops %d  Esc for settings" % [GameState.score, GameState.core_loops_completed]

package/templates/godot-2d/scripts/player.gd

@@ -0,0 +1,10 @@
+extends Node2D
+## A placeholder player: a shape that moves. Swap the Polygon2D for your own art.
+
+const SPEED := 180.0
+
+var bounds := Rect2(16.0, 16.0, 608.0, 352.0)
+
+func _physics_process(delta: float) -> void:
+	var direction := Input.get_vector("move_left", "move_right", "move_up", "move_down")
+	position = (position + direction * SPEED * delta).clamp(bounds.position, bounds.end)

package/templates/godot-2d/scripts/state_hook.gd

@@ -0,0 +1,16 @@
+extends Node
+## Lets a playtest read the game. The driver calls _ravensight_state() on every node
+## in the ravensight_state group. Add what a player can see to this dictionary as the
+## game grows: a persona reads it, and a replay compares it.
+
+@export var player_path: NodePath
+
+func _ready() -> void:
+	add_to_group("ravensight_state")
+
+func _ravensight_state() -> Dictionary:
+	var state := GameState.snapshot()
+	var player := get_node_or_null(player_path) as Node2D
+	if player != null:
+		state["player_position"] = [round(player.position.x), round(player.position.y)]
+	return state

package/templates/godot-2d/template.json

@@ -0,0 +1,14 @@
+{
+  "name": "godot-2d",
+  "version": "1.0.0",
+  "engine": "godot",
+  "min_engine": "4.3",
+  "sdk": {
+    "version": "0.3.1",
+    "source": "https://github.com/Reality-Software-Entertainment/ravensight-godot",
+    "tag": "v0.3.1",
+    "commit": "997d53edfd40641e88f40fd712df711dbb116f78",
+    "path": "addons/ravensight/Ravensight.gd",
+    "sha256": "e7a5dc6f5f0edb62c3265867da2e8da74f5ff3ed2145a8b162d77f2dbb69733e"
+  }
+}

package/templates/godot-2d/tools/inject_release_key.sh

@@ -0,0 +1,19 @@
+#!/bin/sh
+# Writes the public release key into the project just before an export, and removes
+# it after, so it is in the exported build and never in git:
+#
+#   RAVENSIGHT_RELEASE_KEY=gt_pub_... sh tools/inject_release_key.sh godot --headless --export-release Web build/index.html
+#
+# Everything after the script's name is the export command. The development key is
+# never exported: export_presets.cfg leaves it out by name.
+set -eu
+: "${RAVENSIGHT_RELEASE_KEY:?Set RAVENSIGHT_RELEASE_KEY to this game public key, the one that starts gt_pub_.}"
+case "$RAVENSIGHT_RELEASE_KEY" in
+  gt_pub_*) ;;
+  *) echo "A build anyone can download needs a public key, the one that starts gt_pub_." >&2; exit 2 ;;
+esac
+file="ravensight_key.release.cfg"
+trap 'rm -f "$file"' EXIT
+umask 077
+printf '[ravensight]\ningest_key="%s"\n' "$RAVENSIGHT_RELEASE_KEY" > "$file"
+"$@"

package/templates/godot-2d/tools/selftest.gd

@@ -0,0 +1,70 @@
+extends SceneTree
+## Proves the parts of this project a game depends on, headless, with no key:
+##   godot --headless --path . --script tools/selftest.gd
+## Prints one line per check and exits non-zero if any failed.
+
+var failed := 0
+
+func _initialize() -> void:
+	# Autoloads and the scene have to be ready first.
+	process_frame.connect(_run, CONNECT_ONE_SHOT)
+
+func _check(name: String, passed: bool) -> void:
+	print("%s %s" % ["ok  " if passed else "FAIL", name])
+	if not passed:
+		failed += 1
+
+func _run() -> void:
+	var game_config: Node = root.get_node("GameConfig")
+	var telemetry: Node = root.get_node("Telemetry")
+	var game_state: Node = root.get_node("GameState")
+	var sdk: Node = root.get_node("Ravensight")
+
+	# Every kind reaches the event as rs_kind, and a bad one reads as none.
+	for kind in ["level_start", "level_complete", "death", "none"]:
+		_check("rs_kind %s" % kind, telemetry.prepare({}, kind)["rs_kind"] == kind)
+	_check("an unknown kind is sent as none", telemetry.prepare({}, "nonsense")["rs_kind"] == "none")
+	var original := {"a": 1}
+	telemetry.prepare(original, "none")
+	_check("prepare leaves the caller's data alone", not original.has("rs_kind"))
+
+	# The key loader's order, without a key on this machine being read.
+	var dir := OS.get_user_data_dir().path_join("selftest")
+	DirAccess.make_dir_recursive_absolute(dir)
+	var path := dir.path_join("key.cfg")
+	var file := ConfigFile.new()
+	file.set_value("ravensight", "ingest_key", "gt_live_selftest")
+	file.set_value("ravensight", "api_url", "http://127.0.0.1:9")
+	file.save(path)
+	var found: Dictionary = game_config.find_key({"ravensight-key-file": path}, true)
+	_check("a key file argument wins", found["source"] == "argument" and found["key"] == "gt_live_selftest" and found["api_url"] == "http://127.0.0.1:9")
+	_check("--no-key answers none", game_config.find_key({"no-key": "true", "ravensight-key-file": path}, true)["source"] == "none")
+	DirAccess.remove_absolute(path)
+
+	# The opt-out is saved where the SDK reads it, and a later run would honour it.
+	var was_on: bool = telemetry.analytics_enabled()
+	telemetry.set_analytics_enabled(false)
+	_check("opting out is saved", not telemetry.analytics_enabled())
+	telemetry.set_analytics_enabled(true)
+	_check("opting back in clears it", telemetry.analytics_enabled())
+	telemetry.set_analytics_enabled(was_on)
+
+	# What the playable check reads.
+	var before: int = game_state.core_loops_completed
+	game_state.complete_core_loop()
+	_check("a completed loop is counted", game_state.core_loops_completed == before + 1)
+	_check("it is reported as a level completion", telemetry.last_event["data"]["rs_kind"] == "level_complete")
+
+	# The hook a playtest reads, on the real scene.
+	var scene: Node = load("res://scenes/main.tscn").instantiate()
+	root.add_child(scene)
+	var hook: Node = scene.get_node("StateHook")
+	_check("the state node is in the group", hook.is_in_group("ravensight_state"))
+	var state: Dictionary = hook._ravensight_state()
+	_check("the state says how many loops", state.has("core_loops_completed"))
+	_check("the state says where the player is", state.has("player_position"))
+	_check("the SDK is the public one", String(sdk.VERSION).length() > 0)
+	scene.queue_free()
+
+	print("selftest %s" % ("failed" if failed > 0 else "passed"))
+	quit(1 if failed > 0 else 0)

package/templates/godot-3d/README.md

@@ -0,0 +1,49 @@
+# __GAME_NAME__
+
+A small placeholder 3D project from the Ravensight `godot-3d` template (Alpha, a proof of
+concept). Every visual is a primitive mesh, and your own models, art and audio replace
+them. Ravensight does not make a 3D game from a brief: this template, Build a feature
+and Validate changes are the whole of the 3D Alpha.
+
+## Run it
+
+Open this folder in Godot 4, or run `godot --path .`. Move with WASD or the arrow keys
+along the floor, jump with Space or E, and Esc for settings. Walk into the beacon: it
+moves somewhere else, and that is one pass of the core loop. Fall off the floor and you
+start again from the middle.
+
+`godot --headless --path . --script tools/selftest.gd` checks the parts a game
+depends on.
+
+## Analytics
+
+The Ravensight SDK (`addons/ravensight/Ravensight.gd`, MIT, unmodified) is an autoload.
+Report events with `Telemetry.track(name, data, kind)`, where `kind` is `level_start`,
+`level_complete`, `death` or `none`. It always sets `rs_kind`, so an event's name is
+never used to guess what it means.
+
+- **The key.** With no key the SDK does nothing and the game plays the same. To send
+  events, put this game's key in `ravensight_key.cfg`, which git ignores, under
+  `[ravensight]` as `ingest_key="..."`. `scripts/autoload/game_config.gd` says where else
+  a key can come from.
+- **The opt-out.** Esc opens settings, and "Share anonymous analytics" is the player's
+  own choice. The SDK saves it and honours it on every later run.
+- **A build anyone can download.** Use a public key, the one that starts `gt_pub_`, so
+  it is written only into the build:
+
+      RAVENSIGHT_RELEASE_KEY=gt_pub_... sh tools/inject_release_key.sh godot --headless --export-release Web build/web/index.html
+
+## How a playtest reads the game
+
+`scripts/state_hook.gd` is in the `ravensight_state` group, and its
+`_ravensight_state()` answer is what a persona sees and a replay compares. Add what a
+player can see to it as the game grows. Call `GameState.complete_core_loop()` once for
+each pass of the core loop.
+
+A persona plays with keys and input actions, and it can click a node by its path. It
+cannot steer a camera with the mouse, so a feature that needs mouse look cannot be
+played by a persona yet.
+
+Random numbers from the global `randf()` and `randi()` are seeded by a playtest, so a
+replay sees them come out the same. See the replay notes in the CLI's `docs/REPLAY.md`
+for what else holds and what does not.

package/templates/godot-3d/addons/ravensight/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Reality Software Entertainment
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.