Add ScriptBehavior DSL: data-driven, non-Turing-complete UGC scripting
Implements the DSL that docs/architecture/scripting_sandbox.md recommends
as the primary (and, for now, sufficient) approach in place of running
untrusted GDScript in-process: a fixed set of trigger/condition/action
verbs, expressed as plain JSON data, interpreted by trusted GDScript with
zero ability to reference engine singletons, call arbitrary methods, or
execute code.
- ScriptBehavior (scripts/scripting/script_behavior.gd): parses and
validates rules from JSON/Dictionary data. Every trigger, condition
type/op, and verb is checked against an explicit whitelist at parse
time; malformed or unknown entries are dropped and recorded in
rejected_rules, never partially executed. Carries an optional
content_flags passthrough so this data type isn't hostile to future
moderation-queue integration (docs/architecture/content_moderation.md).
- ScriptInterpreterNode (scripts/scripting/script_interpreter.gd): the
only code that executes rules. Triggers: on_interact (proximity +
"interact" input action), on_enter (edge-triggered Area3D overlap),
on_touch (continuous overlap), on_timer (physics-clocked Timer). Verbs:
give_item, play_sound, move, rotate, spawn_from_catalog, set_timer --
each a fixed, hand-written function; verb dispatch is an explicit
match(), never call()-by-name from data. move/rotate animate via Tween
rather than teleporting.
- PlayerInventory (scripts/scripting/player_inventory.gd): a small
per-player item-count stub for give_item to target, since no real
inventory/entity-state system exists yet (M9 Economy). Attached to
scenes/player.tscn as "Inventory".
- SpawnCatalog (scripts/scripting/spawn_catalog.gd): trusted catalog_id ->
asset_id lookup for spawn_from_catalog, mirroring the AvatarCatalog
data-driven-JSON convention. Rule data only ever supplies a catalog_id
key, never a resource path.
- Wired a real demo ("ScriptedChest") into scenes/worlds/test_level.tscn
with an on_interact rule (give_item + play_sound + rotate), plus an
"interact" input action (project.godot).
- scripts/smoke_test_script_behavior.gd: exercises every trigger type,
every verb, and every condition type against the real interpreter and
the wired demo scene, and proves unknown/malformed/unsafe rules
(unknown verb, unknown trigger, non-scalar smuggled arguments, etc.)
are rejected at parse time and never run -- 50/50 checks pass.
This commit is contained in:
@@ -0,0 +1,41 @@
|
||||
class_name PlayerInventory
|
||||
extends Node
|
||||
## Minimal per-player item-count store.
|
||||
##
|
||||
## docs/architecture/dynamic_object_node.gd's header notes that a dynamic
|
||||
## object's runtime state ("position, health, inventory") belongs to "the
|
||||
## entity system" -- but no such system exists yet (M9 Economy hasn't been
|
||||
## built). This is a deliberately small, local stub scoped to make
|
||||
## ScriptBehavior's `give_item` verb demonstrable now, not an attempt to
|
||||
## build the real economy/inventory system. Replace it wholesale when M9
|
||||
## lands; keep the give_item/get_count surface so existing ScriptBehavior
|
||||
## data keeps working against the real thing.
|
||||
##
|
||||
## Attach one of these as a child node named "Inventory" under a player (see
|
||||
## scenes/player.tscn) -- [ScriptInterpreterNode] looks it up by that name
|
||||
## when resolving `target: "player"` for the `give_item` verb.
|
||||
|
||||
## Emitted whenever an item's count changes, with the item's new total.
|
||||
signal item_changed(item_id: String, count: int)
|
||||
|
||||
var _items: Dictionary = {} # item_id (String) -> count (int)
|
||||
|
||||
|
||||
## Add (or, with a negative count, remove) units of an item. Counts never go
|
||||
## negative. `count == 0` is a no-op.
|
||||
func give_item(item_id: String, count: int) -> void:
|
||||
if item_id.is_empty() or count == 0:
|
||||
return
|
||||
var new_count: int = maxi(0, int(_items.get(item_id, 0)) + count)
|
||||
_items[item_id] = new_count
|
||||
item_changed.emit(item_id, new_count)
|
||||
|
||||
|
||||
## Current count for an item (0 if never granted).
|
||||
func get_count(item_id: String) -> int:
|
||||
return int(_items.get(item_id, 0))
|
||||
|
||||
|
||||
## A snapshot of the whole inventory (for UI/debugging/tests).
|
||||
func get_all() -> Dictionary:
|
||||
return _items.duplicate()
|
||||
@@ -0,0 +1,383 @@
|
||||
class_name ScriptBehavior
|
||||
extends RefCounted
|
||||
## A data-driven, non-Turing-complete behavior attached to a world object.
|
||||
##
|
||||
## This is the DSL described in docs/architecture/scripting_sandbox.md §3.1:
|
||||
## a small, fixed set of trigger/condition/action verbs, expressed as plain
|
||||
## JSON/Dictionary data, with zero ability to reference engine singletons,
|
||||
## call arbitrary methods, or execute code. There is no interpreter to
|
||||
## escape because there is no general execution -- every verb is a reviewed,
|
||||
## hand-written GDScript function in [ScriptInterpreterNode], and every verb
|
||||
## argument here is a plain scalar (String, int, float, bool) or a 3-element
|
||||
## Array of numbers, never a Callable/Object/Script.
|
||||
##
|
||||
## Because the data is exactly this restricted, it plugs into the content
|
||||
## moderation pipeline (docs/architecture/content_moderation.md) the same way
|
||||
## an asset or room does: it's a plain JSON blob that can be hashed, stored,
|
||||
## flagged and reviewed without needing to sandbox code execution to do so.
|
||||
##
|
||||
## ## Format
|
||||
##
|
||||
## ```json
|
||||
## {
|
||||
## "rules": [
|
||||
## {
|
||||
## "trigger": {"type": "on_interact"},
|
||||
## "conditions": [
|
||||
## {"type": "item_count", "item_id": "torch", "op": ">=", "value": 1}
|
||||
## ],
|
||||
## "actions": [
|
||||
## {"verb": "give_item", "item_id": "gold_coin", "count": 3},
|
||||
## {"verb": "play_sound", "sound_id": "chest_open"}
|
||||
## ]
|
||||
## }
|
||||
## ]
|
||||
## }
|
||||
## ```
|
||||
##
|
||||
## Any rule that fails validation (unknown trigger/condition/action, wrong
|
||||
## argument types, out-of-range values, an unrecognized key standing in for
|
||||
## one of the whitelisted ones) is **dropped silently from execution** --
|
||||
## never partially applied, never run "best effort". The rejection reason is
|
||||
## recorded in [member rejected_rules] so callers/tests/moderation tooling
|
||||
## can see *why*, but the interpreter never runs a rule that didn't fully
|
||||
## validate.
|
||||
|
||||
# Sibling scripting scripts are referenced via preload rather than by their
|
||||
# global class_name so this module parses correctly from a bare/cold
|
||||
# compile (matches the convention in scripts/avatar/avatar_loadout.gd --
|
||||
# a headless `godot --script` run doesn't always rebuild the global class
|
||||
# registry; only an editor scan / `--import` reliably does).
|
||||
const ScriptRuleClass := preload("res://scripts/scripting/script_rule.gd")
|
||||
|
||||
const VALID_TRIGGERS: Array[String] = ["on_interact", "on_enter", "on_touch", "on_timer"]
|
||||
const VALID_CONDITION_TYPES: Array[String] = ["item_count", "flag", "timer_active", "timer_remaining"]
|
||||
const VALID_OPS: Array[String] = ["==", "!=", "<", "<=", ">", ">="]
|
||||
const VALID_VERBS: Array[String] = ["give_item", "play_sound", "move", "rotate", "spawn_from_catalog", "set_timer"]
|
||||
const VALID_TARGETS: Array[String] = ["self", "player"]
|
||||
const VALID_AXES: Array[String] = ["x", "y", "z"]
|
||||
|
||||
const MAX_STRING_LEN: int = 64
|
||||
const MAX_ITEM_COUNT: int = 100000
|
||||
const MAX_TIMER_SECONDS: float = 3600.0
|
||||
const MAX_DEGREES: float = 100000.0
|
||||
const MAX_OFFSET_MAGNITUDE: float = 10000.0
|
||||
const DEFAULT_MOVE_DURATION: float = 0.4
|
||||
const MIN_DURATION: float = 0.05
|
||||
const MAX_DURATION: float = 5.0
|
||||
|
||||
## Successfully parsed, executable rules (each a ScriptRuleClass instance --
|
||||
## left as a plain untyped Array since Godot's typed-array element type
|
||||
## can't reliably reference a cross-file preloaded const; see the
|
||||
## preload note above).
|
||||
var rules: Array = []
|
||||
|
||||
## Human-readable reasons every rejected rule (or top-level parse failure)
|
||||
## was dropped. Never empty on a fully-clean input, always non-empty
|
||||
## whenever `rules` is missing entries an author intended.
|
||||
var rejected_rules: Array[String] = []
|
||||
|
||||
## Optional passthrough content-moderation metadata (see
|
||||
## docs/architecture/content_moderation.md §7.2 -- "Each content resource
|
||||
## carries a content_flags metadata field"). Not enforced by anything in
|
||||
## this system yet -- scripts as a moderated content type is still an open
|
||||
## item there -- but the field round-trips through parsing so a future
|
||||
## moderation pipeline has somewhere to read/write it without a format
|
||||
## change. Untrusted data can only ever set this to a plain Dictionary of
|
||||
## scalars; it's metadata, never consulted by the interpreter for control
|
||||
## flow.
|
||||
var content_flags: Dictionary = {}
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Construction
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
## Load and parse a ScriptBehavior from a JSON file on disk.
|
||||
static func load_from_file(path: String) -> ScriptBehavior:
|
||||
var behavior := ScriptBehavior.new()
|
||||
var file := FileAccess.open(path, FileAccess.READ)
|
||||
if file == null:
|
||||
behavior.rejected_rules.append(
|
||||
"cannot open '%s' (error %d)" % [path, FileAccess.get_open_error()]
|
||||
)
|
||||
return behavior
|
||||
|
||||
var text := file.get_as_text()
|
||||
file.close()
|
||||
|
||||
var parsed: Variant = JSON.parse_string(text)
|
||||
if parsed == null or not (parsed is Dictionary):
|
||||
behavior.rejected_rules.append("invalid JSON in '%s'" % path)
|
||||
return behavior
|
||||
|
||||
behavior._parse(parsed as Dictionary)
|
||||
return behavior
|
||||
|
||||
|
||||
## Parse a ScriptBehavior from an already-decoded Dictionary (e.g. embedded
|
||||
## inline in a WorldObject's `properties["script_behavior"]`).
|
||||
static func load_from_dict(data: Dictionary) -> ScriptBehavior:
|
||||
var behavior := ScriptBehavior.new()
|
||||
behavior._parse(data)
|
||||
return behavior
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Parsing / validation
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
func _parse(data: Dictionary) -> void:
|
||||
var raw_flags: Variant = data.get("content_flags")
|
||||
if raw_flags is Dictionary:
|
||||
content_flags = raw_flags as Dictionary
|
||||
|
||||
var raw_rules: Variant = data.get("rules")
|
||||
if not (raw_rules is Array):
|
||||
rejected_rules.append("top-level 'rules' key missing or not an array")
|
||||
return
|
||||
|
||||
for entry in (raw_rules as Array):
|
||||
if not (entry is Dictionary):
|
||||
rejected_rules.append("rule entry is not an object: %s" % str(entry))
|
||||
continue
|
||||
var rule := _parse_rule(entry as Dictionary)
|
||||
if rule != null:
|
||||
rules.append(rule)
|
||||
|
||||
|
||||
func _parse_rule(rule_dict: Dictionary) -> ScriptRuleClass:
|
||||
var trigger: Variant = rule_dict.get("trigger")
|
||||
if not (trigger is Dictionary):
|
||||
rejected_rules.append("rule missing a 'trigger' object")
|
||||
return null
|
||||
|
||||
var trigger_type: Variant = (trigger as Dictionary).get("type")
|
||||
if not (trigger_type is String) or not VALID_TRIGGERS.has(trigger_type):
|
||||
rejected_rules.append("rule has unknown/missing trigger type: %s" % str(trigger_type))
|
||||
return null
|
||||
|
||||
var interval: float = 0.0
|
||||
if trigger_type == "on_timer":
|
||||
var raw_interval: Variant = (trigger as Dictionary).get("interval")
|
||||
if not _is_number(raw_interval) or float(raw_interval) <= 0.0 or float(raw_interval) > MAX_TIMER_SECONDS:
|
||||
rejected_rules.append("on_timer rule has invalid 'interval': %s" % str(raw_interval))
|
||||
return null
|
||||
interval = float(raw_interval)
|
||||
|
||||
var conditions: Array[Dictionary] = []
|
||||
var raw_conditions: Variant = rule_dict.get("conditions", [])
|
||||
if not (raw_conditions is Array):
|
||||
rejected_rules.append("rule 'conditions' is not an array")
|
||||
return null
|
||||
for raw_cond in (raw_conditions as Array):
|
||||
if not (raw_cond is Dictionary):
|
||||
rejected_rules.append("condition entry is not an object: %s" % str(raw_cond))
|
||||
return null
|
||||
var cond := _parse_condition(raw_cond as Dictionary)
|
||||
if cond.is_empty():
|
||||
return null
|
||||
conditions.append(cond)
|
||||
|
||||
var actions: Array[Dictionary] = []
|
||||
var raw_actions: Variant = rule_dict.get("actions", [])
|
||||
if not (raw_actions is Array) or raw_actions.is_empty():
|
||||
rejected_rules.append("rule 'actions' is missing, not an array, or empty")
|
||||
return null
|
||||
for raw_action in (raw_actions as Array):
|
||||
if not (raw_action is Dictionary):
|
||||
rejected_rules.append("action entry is not an object: %s" % str(raw_action))
|
||||
return null
|
||||
var action := _parse_action(raw_action as Dictionary)
|
||||
if action.is_empty():
|
||||
return null
|
||||
actions.append(action)
|
||||
|
||||
var rule := ScriptRuleClass.new()
|
||||
rule.trigger_type = trigger_type
|
||||
rule.trigger_interval = interval
|
||||
rule.conditions = conditions
|
||||
rule.actions = actions
|
||||
return rule
|
||||
|
||||
|
||||
## Returns a normalized condition Dictionary, or {} (empty) if invalid --
|
||||
## the empty dict is the "rejected" sentinel since a valid condition always
|
||||
## has at least "type" and "op".
|
||||
func _parse_condition(raw: Dictionary) -> Dictionary:
|
||||
var cond_type: Variant = raw.get("type")
|
||||
if not (cond_type is String) or not VALID_CONDITION_TYPES.has(cond_type):
|
||||
rejected_rules.append("condition has unknown/missing type: %s" % str(cond_type))
|
||||
return {}
|
||||
|
||||
var op: Variant = raw.get("op")
|
||||
if not (op is String) or not VALID_OPS.has(op):
|
||||
rejected_rules.append("condition has unknown/missing op: %s" % str(op))
|
||||
return {}
|
||||
|
||||
var value: Variant = raw.get("value")
|
||||
if not _is_scalar(value):
|
||||
rejected_rules.append("condition 'value' is not a plain scalar: %s" % str(value))
|
||||
return {}
|
||||
|
||||
# Relational ops only make sense against numbers -- reject up front
|
||||
# rather than silently coercing at eval time.
|
||||
if op != "==" and op != "!=" and not _is_number(value):
|
||||
rejected_rules.append("condition op '%s' requires a numeric value" % op)
|
||||
return {}
|
||||
|
||||
match cond_type:
|
||||
"item_count":
|
||||
var item_id: Variant = raw.get("item_id")
|
||||
if not _is_valid_id_string(item_id):
|
||||
rejected_rules.append("item_count condition has invalid item_id: %s" % str(item_id))
|
||||
return {}
|
||||
return {"type": "item_count", "op": op, "value": value, "item_id": item_id}
|
||||
"flag":
|
||||
var name: Variant = raw.get("name")
|
||||
if not _is_valid_id_string(name):
|
||||
rejected_rules.append("flag condition has invalid name: %s" % str(name))
|
||||
return {}
|
||||
return {"type": "flag", "op": op, "value": value, "name": name}
|
||||
"timer_active", "timer_remaining":
|
||||
var timer_name: Variant = raw.get("name")
|
||||
if not _is_valid_id_string(timer_name):
|
||||
rejected_rules.append("%s condition has invalid name: %s" % [cond_type, str(timer_name)])
|
||||
return {}
|
||||
return {"type": cond_type, "op": op, "value": value, "name": timer_name}
|
||||
# Unreachable given the VALID_CONDITION_TYPES check above, but never
|
||||
# fall through to something that looks valid.
|
||||
return {}
|
||||
|
||||
|
||||
## Returns a normalized action Dictionary, or {} (empty) if invalid.
|
||||
func _parse_action(raw: Dictionary) -> Dictionary:
|
||||
var verb: Variant = raw.get("verb")
|
||||
if not (verb is String) or not VALID_VERBS.has(verb):
|
||||
rejected_rules.append("action has unknown/missing verb: %s" % str(verb))
|
||||
return {}
|
||||
|
||||
match verb:
|
||||
"give_item":
|
||||
var item_id: Variant = raw.get("item_id")
|
||||
var count: Variant = raw.get("count")
|
||||
if not _is_valid_id_string(item_id):
|
||||
rejected_rules.append("give_item has invalid item_id: %s" % str(item_id))
|
||||
return {}
|
||||
if not _is_number(count) or int(count) <= 0 or int(count) > MAX_ITEM_COUNT:
|
||||
rejected_rules.append("give_item has invalid count: %s" % str(count))
|
||||
return {}
|
||||
return {"verb": "give_item", "item_id": item_id, "count": int(count)}
|
||||
|
||||
"play_sound":
|
||||
var sound_id: Variant = raw.get("sound_id")
|
||||
if not _is_valid_id_string(sound_id):
|
||||
rejected_rules.append("play_sound has invalid sound_id: %s" % str(sound_id))
|
||||
return {}
|
||||
return {"verb": "play_sound", "sound_id": sound_id}
|
||||
|
||||
"move":
|
||||
var target: Variant = raw.get("target", "self")
|
||||
var offset: Variant = _parse_vector3(raw.get("offset"), MAX_OFFSET_MAGNITUDE)
|
||||
var duration: Variant = _parse_duration(raw.get("duration", DEFAULT_MOVE_DURATION))
|
||||
if not (target is String) or not VALID_TARGETS.has(target):
|
||||
rejected_rules.append("move has invalid target: %s" % str(target))
|
||||
return {}
|
||||
if offset == null:
|
||||
rejected_rules.append("move has invalid offset: %s" % str(raw.get("offset")))
|
||||
return {}
|
||||
if duration == null:
|
||||
rejected_rules.append("move has invalid duration: %s" % str(raw.get("duration")))
|
||||
return {}
|
||||
return {"verb": "move", "target": target, "offset": offset, "duration": duration}
|
||||
|
||||
"rotate":
|
||||
var r_target: Variant = raw.get("target", "self")
|
||||
var degrees: Variant = raw.get("degrees")
|
||||
var axis: Variant = raw.get("axis", "y")
|
||||
var r_duration: Variant = _parse_duration(raw.get("duration", DEFAULT_MOVE_DURATION))
|
||||
if not (r_target is String) or not VALID_TARGETS.has(r_target):
|
||||
rejected_rules.append("rotate has invalid target: %s" % str(r_target))
|
||||
return {}
|
||||
if not _is_number(degrees) or absf(float(degrees)) > MAX_DEGREES:
|
||||
rejected_rules.append("rotate has invalid degrees: %s" % str(degrees))
|
||||
return {}
|
||||
if not (axis is String) or not VALID_AXES.has(axis):
|
||||
rejected_rules.append("rotate has invalid axis: %s" % str(axis))
|
||||
return {}
|
||||
if r_duration == null:
|
||||
rejected_rules.append("rotate has invalid duration: %s" % str(raw.get("duration")))
|
||||
return {}
|
||||
return {"verb": "rotate", "target": r_target, "degrees": float(degrees), "axis": axis, "duration": r_duration}
|
||||
|
||||
"spawn_from_catalog":
|
||||
var catalog_id: Variant = raw.get("catalog_id")
|
||||
var position: Variant = _parse_vector3(raw.get("position"), MAX_OFFSET_MAGNITUDE)
|
||||
if not _is_valid_id_string(catalog_id):
|
||||
rejected_rules.append("spawn_from_catalog has invalid catalog_id: %s" % str(catalog_id))
|
||||
return {}
|
||||
if position == null:
|
||||
rejected_rules.append("spawn_from_catalog has invalid position: %s" % str(raw.get("position")))
|
||||
return {}
|
||||
return {"verb": "spawn_from_catalog", "catalog_id": catalog_id, "position": position}
|
||||
|
||||
"set_timer":
|
||||
var timer_name: Variant = raw.get("name")
|
||||
var seconds: Variant = raw.get("seconds")
|
||||
if not _is_valid_id_string(timer_name):
|
||||
rejected_rules.append("set_timer has invalid name: %s" % str(timer_name))
|
||||
return {}
|
||||
if not _is_number(seconds) or float(seconds) <= 0.0 or float(seconds) > MAX_TIMER_SECONDS:
|
||||
rejected_rules.append("set_timer has invalid seconds: %s" % str(seconds))
|
||||
return {}
|
||||
return {"verb": "set_timer", "name": timer_name, "seconds": float(seconds)}
|
||||
|
||||
# Unreachable given the VALID_VERBS check above.
|
||||
return {}
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Scalar validation helpers
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
func _is_number(v: Variant) -> bool:
|
||||
return v is int or v is float
|
||||
|
||||
|
||||
## A "plain scalar" -- the only shapes a condition/action value is ever
|
||||
## allowed to be. Deliberately excludes Dictionary, Array, Object, Callable,
|
||||
## Node, Resource -- there is no representable way for UGC data to hand the
|
||||
## interpreter anything but a bare String/int/float/bool.
|
||||
func _is_scalar(v: Variant) -> bool:
|
||||
return v is String or v is int or v is float or v is bool
|
||||
|
||||
|
||||
## Identifiers (item ids, sound ids, catalog ids, flag/timer names) are
|
||||
## always plain, short, non-empty strings -- never used as a path, never
|
||||
## passed to load()/call() directly, only ever looked up as a Dictionary
|
||||
## key against a trusted, code-defined table.
|
||||
func _is_valid_id_string(v: Variant) -> bool:
|
||||
if not (v is String):
|
||||
return false
|
||||
var s: String = v
|
||||
return not s.is_empty() and s.length() <= MAX_STRING_LEN
|
||||
|
||||
|
||||
func _parse_duration(raw: Variant) -> Variant:
|
||||
if not _is_number(raw):
|
||||
return null
|
||||
var d: float = clampf(float(raw), MIN_DURATION, MAX_DURATION)
|
||||
return d
|
||||
|
||||
|
||||
## Parses a JSON array of exactly 3 numbers into a Vector3. Returns null
|
||||
## (never a partially-applied Vector3) on anything else.
|
||||
func _parse_vector3(raw: Variant, max_component: float) -> Variant:
|
||||
if not (raw is Array) or (raw as Array).size() != 3:
|
||||
return null
|
||||
var comps: Array = []
|
||||
for c in (raw as Array):
|
||||
if not _is_number(c) or absf(float(c)) > max_component:
|
||||
return null
|
||||
comps.append(float(c))
|
||||
return Vector3(comps[0], comps[1], comps[2])
|
||||
@@ -0,0 +1,459 @@
|
||||
class_name ScriptInterpreterNode
|
||||
extends Node3D
|
||||
## Trusted interpreter for a [ScriptBehavior] attached to a world object.
|
||||
##
|
||||
## This is the **only** code that ever executes a ScriptBehavior's rules.
|
||||
## The rule data (ScriptBehavior / ScriptRule) is plain JSON-shaped
|
||||
## Dictionaries -- it is never handed to `eval`, never passed through
|
||||
## [Expression], and never used to call a method by a name that came from
|
||||
## the data. Every verb is dispatched through an explicit `match` in
|
||||
## [method _execute_action], and every argument reaches the engine only
|
||||
## after [ScriptBehavior] has validated it's a plain scalar / 3-vector and
|
||||
## this class has resolved it through a fixed, code-defined path (a
|
||||
## Dictionary lookup on a whitelisted catalog, a child node named
|
||||
## "Inventory", etc). There is no reachable path from rule data to
|
||||
## OS/FileAccess/networking/ClassDB/Callable. See
|
||||
## docs/architecture/scripting_sandbox.md §3.1 for the design rationale.
|
||||
##
|
||||
## ## Usage
|
||||
##
|
||||
## Attach this script directly to the Node3D that represents the object in
|
||||
## the scene (see the "ScriptedChest" node in scenes/worlds/test_level.tscn
|
||||
## for a worked example). Either set [member behavior_path] (loaded on
|
||||
## [method _ready]) or call [method set_behavior] directly with an
|
||||
## already-parsed [ScriptBehavior] (e.g. from tests).
|
||||
##
|
||||
## Triggers:
|
||||
## - `on_interact`: player presses the "interact" action while within
|
||||
## [member interact_radius] of this node.
|
||||
## - `on_enter`: fires once, edge-triggered, when a player's body starts
|
||||
## overlapping this node's trigger volume.
|
||||
## - `on_touch`: fires every physics frame while a player's body is
|
||||
## overlapping this node's trigger volume (continuous contact).
|
||||
## - `on_timer`: fires on a repeating interval regardless of any player,
|
||||
## via a dedicated [Timer] child per on_timer rule.
|
||||
|
||||
# Sibling scripting scripts are referenced via preload rather than by their
|
||||
# global class_name so this module parses correctly from a bare/cold
|
||||
# compile -- see the note in script_behavior.gd.
|
||||
const ScriptBehaviorClass := preload("res://scripts/scripting/script_behavior.gd")
|
||||
const SpawnCatalogClass := preload("res://scripts/scripting/spawn_catalog.gd")
|
||||
const PlayerInventoryClass := preload("res://scripts/scripting/player_inventory.gd")
|
||||
|
||||
## Emitted every time a verb actually executes, for observability/tests.
|
||||
## `args` is the normalized action Dictionary that was executed.
|
||||
signal verb_executed(verb: String, args: Dictionary)
|
||||
|
||||
## Emitted for every rule ScriptBehavior rejected at parse time (so callers
|
||||
## can surface this in an editor / moderation tool).
|
||||
signal rule_rejected(reason: String)
|
||||
|
||||
## JSON file to load the behavior from, if [member behavior] isn't set
|
||||
## directly before this node enters the tree.
|
||||
@export var behavior_path: String = ""
|
||||
|
||||
## How close (metres) a player must be for `on_interact` and to count as
|
||||
## "in range" for the interact input check.
|
||||
@export var interact_radius: float = 2.5
|
||||
|
||||
## Collision layer bit the player's body is on (see scenes/player.tscn --
|
||||
## Player.collision_layer = 2). Used as this node's trigger Area3D's
|
||||
## collision_mask so it only ever notices players, nothing else.
|
||||
@export var player_collision_mask: int = 2
|
||||
|
||||
## The parsed behavior this node interprets. Set directly (tests) or leave
|
||||
## null and set [member behavior_path] to load one on [method _ready].
|
||||
var behavior: ScriptBehaviorClass = null
|
||||
|
||||
var _area: Area3D = null
|
||||
var _players_in_range: Array[Node] = []
|
||||
var _entered_once: Dictionary = {} # body instance id (int) -> true
|
||||
|
||||
# Local, per-object whitelisted state store (see docs/architecture/
|
||||
# scripting_sandbox.md §4 open question re: static analysis of "what a
|
||||
# script can possibly do" -- flags/timers are always plain scalars here).
|
||||
var _flags: Dictionary = {} # name (String) -> scalar
|
||||
var _timers: Dictionary = {} # name (String) -> {"remaining": float, "active": bool}
|
||||
|
||||
var _timer_nodes: Array[Timer] = []
|
||||
var _spawn_catalog: SpawnCatalogClass = null
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Lifecycle
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
func _ready() -> void:
|
||||
if behavior == null and not behavior_path.is_empty():
|
||||
behavior = ScriptBehaviorClass.load_from_file(behavior_path)
|
||||
_apply_loaded_behavior()
|
||||
|
||||
|
||||
## Assign an already-parsed behavior (e.g. from a test, or built inline
|
||||
## rather than loaded from a file). Safe to call before or after this node
|
||||
## enters the tree.
|
||||
func set_behavior(new_behavior: ScriptBehaviorClass) -> void:
|
||||
behavior = new_behavior
|
||||
if is_inside_tree():
|
||||
_apply_loaded_behavior()
|
||||
|
||||
|
||||
func _apply_loaded_behavior() -> void:
|
||||
if behavior == null:
|
||||
return
|
||||
for msg in behavior.rejected_rules:
|
||||
push_warning("ScriptInterpreterNode(%s): rejected rule -- %s" % [name, msg])
|
||||
rule_rejected.emit(msg)
|
||||
_setup_area()
|
||||
_setup_timers()
|
||||
|
||||
|
||||
func _setup_area() -> void:
|
||||
if _area != null:
|
||||
_area.queue_free()
|
||||
_area = null
|
||||
|
||||
_area = Area3D.new()
|
||||
_area.name = "_ScriptTriggerArea"
|
||||
_area.collision_layer = 0
|
||||
_area.collision_mask = player_collision_mask
|
||||
_area.monitoring = true
|
||||
_area.monitorable = false
|
||||
|
||||
var shape := CollisionShape3D.new()
|
||||
var sphere := SphereShape3D.new()
|
||||
sphere.radius = interact_radius
|
||||
shape.shape = sphere
|
||||
_area.add_child(shape)
|
||||
|
||||
add_child(_area)
|
||||
_area.body_entered.connect(_on_body_entered)
|
||||
_area.body_exited.connect(_on_body_exited)
|
||||
|
||||
|
||||
func _setup_timers() -> void:
|
||||
for t in _timer_nodes:
|
||||
if is_instance_valid(t):
|
||||
t.queue_free()
|
||||
_timer_nodes.clear()
|
||||
|
||||
if behavior == null:
|
||||
return
|
||||
for rule in behavior.rules:
|
||||
if rule.trigger_type != "on_timer":
|
||||
continue
|
||||
var timer := Timer.new()
|
||||
timer.wait_time = rule.trigger_interval
|
||||
timer.autostart = true
|
||||
timer.one_shot = false
|
||||
# Tied to the fixed physics step (not idle/process delta) so
|
||||
# on_timer fires deterministically off the simulation clock,
|
||||
# matching physics_ticks_per_second (see project.godot §physics)
|
||||
# rather than however fast the host happens to be rendering.
|
||||
timer.process_callback = Timer.TIMER_PROCESS_PHYSICS
|
||||
add_child(timer)
|
||||
timer.timeout.connect(_on_rule_timer_timeout.bind(rule))
|
||||
_timer_nodes.append(timer)
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Trigger sources
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
func _is_player_body(body: Node) -> bool:
|
||||
# Player carries a global class_name (scripts/player.gd); this stays a
|
||||
# plain `is` check against a known engine/script type, never a
|
||||
# data-driven dispatch.
|
||||
return body is CharacterBody3D and body.has_node("Inventory")
|
||||
|
||||
|
||||
func _on_body_entered(body: Node) -> void:
|
||||
if not _is_player_body(body):
|
||||
return
|
||||
if not _players_in_range.has(body):
|
||||
_players_in_range.append(body)
|
||||
var id := body.get_instance_id()
|
||||
if not _entered_once.has(id):
|
||||
_entered_once[id] = true
|
||||
fire("on_enter", body)
|
||||
|
||||
|
||||
func _on_body_exited(body: Node) -> void:
|
||||
_players_in_range.erase(body)
|
||||
_entered_once.erase(body.get_instance_id())
|
||||
|
||||
|
||||
func _unhandled_input(event: InputEvent) -> void:
|
||||
if _players_in_range.is_empty():
|
||||
return
|
||||
if event.is_action_pressed("interact") and not event.is_echo():
|
||||
fire("on_interact", _players_in_range[0])
|
||||
|
||||
|
||||
func _on_rule_timer_timeout(rule) -> void:
|
||||
_fire_rule(rule, null)
|
||||
|
||||
|
||||
func _physics_process(delta: float) -> void:
|
||||
# Continuous on_touch contact -- checked every physics frame while
|
||||
# overlapping, unlike the edge-triggered on_enter above.
|
||||
if behavior != null and _area != null:
|
||||
for body in _area.get_overlapping_bodies():
|
||||
if _is_player_body(body):
|
||||
fire("on_touch", body)
|
||||
|
||||
# Tick down local timers set via the set_timer verb.
|
||||
for t_name in _timers.keys():
|
||||
var t: Dictionary = _timers[t_name]
|
||||
if t.get("active", false):
|
||||
t["remaining"] = maxf(0.0, float(t.get("remaining", 0.0)) - delta)
|
||||
if t["remaining"] <= 0.0:
|
||||
t["active"] = false
|
||||
_timers[t_name] = t
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Public firing API -- this is what every trigger source above calls, and
|
||||
# what a test can call directly to exercise a rule deterministically.
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
## Fire every rule of the given trigger type whose conditions currently
|
||||
## hold, in order. `player` is the entity that caused the trigger (may be
|
||||
## null for `on_timer`, which has no player context).
|
||||
func fire(trigger_type: String, player: Node) -> void:
|
||||
if behavior == null:
|
||||
return
|
||||
for rule in behavior.rules:
|
||||
if rule.trigger_type == trigger_type:
|
||||
_fire_rule(rule, player)
|
||||
|
||||
|
||||
func _fire_rule(rule, player: Node) -> void:
|
||||
if not _conditions_met(rule.conditions, player):
|
||||
return
|
||||
for action in rule.actions:
|
||||
_execute_action(action, player)
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Condition evaluation -- reads only the small whitelisted state store
|
||||
# (item counts via a player's Inventory, local flags, local timer state).
|
||||
# No expression evaluation, no arbitrary field access.
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
func _conditions_met(conditions: Array[Dictionary], player: Node) -> bool:
|
||||
for cond in conditions:
|
||||
if not _eval_condition(cond, player):
|
||||
return false
|
||||
return true
|
||||
|
||||
|
||||
func _eval_condition(cond: Dictionary, player: Node) -> bool:
|
||||
var op: String = cond.get("op", "")
|
||||
var expected: Variant = cond.get("value")
|
||||
var actual: Variant = null
|
||||
|
||||
match cond.get("type", ""):
|
||||
"item_count":
|
||||
var inv := _get_inventory(player)
|
||||
if inv == null:
|
||||
return false
|
||||
actual = inv.get_count(cond.get("item_id", ""))
|
||||
"flag":
|
||||
actual = _flags.get(cond.get("name", ""), false)
|
||||
"timer_active":
|
||||
var t: Dictionary = _timers.get(cond.get("name", ""), {})
|
||||
actual = t.get("active", false)
|
||||
"timer_remaining":
|
||||
var tr: Dictionary = _timers.get(cond.get("name", ""), {})
|
||||
actual = tr.get("remaining", 0.0)
|
||||
_:
|
||||
return false
|
||||
|
||||
return _compare(actual, op, expected)
|
||||
|
||||
|
||||
func _compare(actual: Variant, op: String, expected: Variant) -> bool:
|
||||
match op:
|
||||
"==":
|
||||
return actual == expected
|
||||
"!=":
|
||||
return actual != expected
|
||||
"<", "<=", ">", ">=":
|
||||
if not ((actual is int or actual is float) and (expected is int or expected is float)):
|
||||
return false
|
||||
var a: float = float(actual)
|
||||
var b: float = float(expected)
|
||||
match op:
|
||||
"<":
|
||||
return a < b
|
||||
"<=":
|
||||
return a <= b
|
||||
">":
|
||||
return a > b
|
||||
">=":
|
||||
return a >= b
|
||||
return false
|
||||
|
||||
|
||||
## Set a local flag on this object's whitelisted state store. Not driven by
|
||||
## any ScriptBehavior verb yet (the verb list in the task spec has no
|
||||
## setter) -- exposed for forward compatibility / tests exercising `flag`
|
||||
## conditions without needing a real gameplay event to set one.
|
||||
func set_flag(flag_name: String, value: Variant) -> void:
|
||||
if not (value is String or value is int or value is float or value is bool):
|
||||
return
|
||||
_flags[flag_name] = value
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Verb dispatch -- the entire attack surface this system deliberately does
|
||||
# NOT have. Every branch is a fixed, hand-written function; nothing here is
|
||||
# ever `call()`-ed by a name that came from data.
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
func _execute_action(action: Dictionary, player: Node) -> void:
|
||||
match action.get("verb", ""):
|
||||
"give_item":
|
||||
_act_give_item(action, player)
|
||||
"play_sound":
|
||||
_act_play_sound(action, player)
|
||||
"move":
|
||||
_act_move(action, player)
|
||||
"rotate":
|
||||
_act_rotate(action, player)
|
||||
"spawn_from_catalog":
|
||||
_act_spawn_from_catalog(action, player)
|
||||
"set_timer":
|
||||
_act_set_timer(action, player)
|
||||
_:
|
||||
# Unreachable in practice -- ScriptBehavior rejects unknown
|
||||
# verbs at parse time, so this branch should never see a rule
|
||||
# at all. Fail safe (do nothing) if it somehow does.
|
||||
push_warning("ScriptInterpreterNode(%s): refused to run unknown verb '%s'" % [name, str(action.get("verb"))])
|
||||
|
||||
|
||||
func _resolve_target(target: String, player: Node) -> Node3D:
|
||||
match target:
|
||||
"self":
|
||||
return self
|
||||
"player":
|
||||
return player if player is Node3D else null
|
||||
return null
|
||||
|
||||
|
||||
func _get_inventory(player: Node) -> PlayerInventoryClass:
|
||||
if player == null:
|
||||
return null
|
||||
var inv: Node = player.get_node_or_null("Inventory")
|
||||
if inv is PlayerInventoryClass:
|
||||
return inv as PlayerInventoryClass
|
||||
return null
|
||||
|
||||
|
||||
func _act_give_item(action: Dictionary, player: Node) -> void:
|
||||
var inv := _get_inventory(player)
|
||||
if inv == null:
|
||||
push_warning("ScriptInterpreterNode(%s): give_item has no player Inventory to target" % name)
|
||||
return
|
||||
inv.give_item(action.get("item_id", ""), int(action.get("count", 0)))
|
||||
verb_executed.emit("give_item", action)
|
||||
|
||||
|
||||
func _act_play_sound(action: Dictionary, _player: Node) -> void:
|
||||
# No real audio asset catalog exists in this repo yet. The verb still
|
||||
# runs through a real, trusted playback path -- attempting to resolve
|
||||
# and play a stream when one is registered -- so it's not a no-op
|
||||
# pretending to be a verb; it's just that today's trusted sound table
|
||||
# is empty. `sound_id` is only ever used as a key into that trusted,
|
||||
# code-defined table below, never as a path handed to load() directly.
|
||||
var sound_id: String = action.get("sound_id", "")
|
||||
var stream_path: String = _TRUSTED_SOUND_TABLE.get(sound_id, "")
|
||||
if not stream_path.is_empty() and ResourceLoader.exists(stream_path):
|
||||
var stream: Resource = load(stream_path)
|
||||
if stream is AudioStream:
|
||||
var player_node := AudioStreamPlayer3D.new()
|
||||
player_node.stream = stream
|
||||
add_child(player_node)
|
||||
player_node.finished.connect(player_node.queue_free)
|
||||
player_node.play()
|
||||
verb_executed.emit("play_sound", action)
|
||||
|
||||
|
||||
## Trusted, code-defined mapping from sound_id -> resource path. Rule data
|
||||
## supplies only the key; this table (not the data) decides what actually
|
||||
## plays. Empty for now -- no sound assets exist in this repo yet.
|
||||
const _TRUSTED_SOUND_TABLE: Dictionary = {}
|
||||
|
||||
|
||||
func _act_move(action: Dictionary, player: Node) -> void:
|
||||
var target_node := _resolve_target(action.get("target", "self"), player)
|
||||
if target_node == null:
|
||||
push_warning("ScriptInterpreterNode(%s): move has no valid target" % name)
|
||||
return
|
||||
var offset: Vector3 = action.get("offset", Vector3.ZERO)
|
||||
var duration: float = float(action.get("duration", ScriptBehaviorClass.DEFAULT_MOVE_DURATION))
|
||||
var dest: Vector3 = target_node.global_position + offset
|
||||
var tween := target_node.create_tween()
|
||||
tween.tween_property(target_node, "global_position", dest, duration)
|
||||
verb_executed.emit("move", action)
|
||||
|
||||
|
||||
func _act_rotate(action: Dictionary, player: Node) -> void:
|
||||
var target_node := _resolve_target(action.get("target", "self"), player)
|
||||
if target_node == null:
|
||||
push_warning("ScriptInterpreterNode(%s): rotate has no valid target" % name)
|
||||
return
|
||||
var degrees: float = float(action.get("degrees", 0.0))
|
||||
var axis: String = action.get("axis", "y")
|
||||
var duration: float = float(action.get("duration", ScriptBehaviorClass.DEFAULT_MOVE_DURATION))
|
||||
var delta_rot := Vector3.ZERO
|
||||
match axis:
|
||||
"x":
|
||||
delta_rot.x = degrees
|
||||
"y":
|
||||
delta_rot.y = degrees
|
||||
"z":
|
||||
delta_rot.z = degrees
|
||||
var dest: Vector3 = target_node.rotation_degrees + delta_rot
|
||||
var tween := target_node.create_tween()
|
||||
tween.tween_property(target_node, "rotation_degrees", dest, duration)
|
||||
verb_executed.emit("rotate", action)
|
||||
|
||||
|
||||
func _act_spawn_from_catalog(action: Dictionary, _player: Node) -> void:
|
||||
if _spawn_catalog == null:
|
||||
_spawn_catalog = SpawnCatalogClass.new()
|
||||
_spawn_catalog.load_catalog()
|
||||
var catalog_id: String = action.get("catalog_id", "")
|
||||
var entry: Dictionary = _spawn_catalog.resolve(catalog_id)
|
||||
if entry.is_empty():
|
||||
push_warning("ScriptInterpreterNode(%s): spawn_from_catalog unknown catalog_id '%s'" % [name, catalog_id])
|
||||
return
|
||||
|
||||
var asset_id: String = entry.get("asset_id", "")
|
||||
var position: Vector3 = action.get("position", Vector3.ZERO)
|
||||
|
||||
# Both WorldObject and DynamicObjectNode carry a global class_name and
|
||||
# are already relied on elsewhere in the project (scripts/chunk_scene.gd)
|
||||
# without preloading -- consistent with that existing convention.
|
||||
var obj := WorldObject.new(
|
||||
"spawned_%d" % Time.get_ticks_usec(), "prop", asset_id,
|
||||
position, Vector4(0, 0, 0, 1), Vector3.ONE, {}, true
|
||||
)
|
||||
var node := DynamicObjectNode.new()
|
||||
node.world_object = obj
|
||||
node.position = position
|
||||
node.name = "spawned_%s" % obj.id
|
||||
|
||||
var host := get_parent() if get_parent() != null else get_tree().current_scene
|
||||
if host != null:
|
||||
host.add_child(node)
|
||||
verb_executed.emit("spawn_from_catalog", action)
|
||||
|
||||
|
||||
func _act_set_timer(action: Dictionary, _player: Node) -> void:
|
||||
var timer_name: String = action.get("name", "")
|
||||
var seconds: float = float(action.get("seconds", 0.0))
|
||||
_timers[timer_name] = {"remaining": seconds, "active": true}
|
||||
verb_executed.emit("set_timer", action)
|
||||
@@ -0,0 +1,32 @@
|
||||
class_name ScriptRule
|
||||
extends RefCounted
|
||||
## One parsed, validated rule: WHEN [trigger] IF [conditions] THEN [actions].
|
||||
##
|
||||
## Rules are parsed once, by [ScriptBehavior], from a plain [Dictionary] that
|
||||
## ultimately comes from untrusted UGC data (a JSON file on disk, or a dict
|
||||
## embedded in a [WorldObject]'s `properties`). Every field on this class is
|
||||
## a plain scalar (String/int/float/bool) or a small [Dictionary]/[Array] of
|
||||
## scalars -- never a [Callable], a [Script], a [Node] reference, or anything
|
||||
## else the data could use to reach into the engine. [ScriptInterpreterNode]
|
||||
## is the only code that reads these fields, and it does so through an
|
||||
## explicit `match` over a fixed whitelist -- see script_interpreter.gd.
|
||||
##
|
||||
## See docs/architecture/scripting_sandbox.md for why the data format has to
|
||||
## look like this (no eval, no Expression, no call-by-name).
|
||||
|
||||
## One of "on_interact", "on_enter", "on_touch", "on_timer".
|
||||
var trigger_type: String = ""
|
||||
|
||||
## Only meaningful when trigger_type == "on_timer": seconds between firings.
|
||||
var trigger_interval: float = 0.0
|
||||
|
||||
## Normalized condition dicts. Each has a "type" (one of
|
||||
## ScriptBehavior.VALID_CONDITION_TYPES), an "op" (one of
|
||||
## ScriptBehavior.VALID_OPS) and scalar operands -- see script_behavior.gd
|
||||
## for the exact per-type shape.
|
||||
var conditions: Array[Dictionary] = []
|
||||
|
||||
## Normalized action dicts. Each has a "verb" (one of
|
||||
## ScriptBehavior.VALID_VERBS) and scalar arguments -- see
|
||||
## script_behavior.gd for the exact per-verb shape.
|
||||
var actions: Array[Dictionary] = []
|
||||
@@ -0,0 +1,55 @@
|
||||
class_name SpawnCatalog
|
||||
extends RefCounted
|
||||
## Catalog of spawnable object templates for ScriptBehavior's
|
||||
## `spawn_from_catalog` verb.
|
||||
##
|
||||
## Mirrors the loading convention of [AvatarCatalog]
|
||||
## (assets/avatars/catalog.json / scripts/avatar/avatar_catalog.gd) --
|
||||
## a data-driven JSON manifest, loaded once, looked up by id.
|
||||
##
|
||||
## Crucially, a ScriptBehavior rule only ever supplies a `catalog_id`
|
||||
## *key* -- never a resource path. The mapping from key to actual asset
|
||||
## path lives entirely in this trusted, code-shipped JSON file. A
|
||||
## malicious/malformed catalog_id in UGC data just fails to resolve
|
||||
## ([method resolve] returns an empty Dictionary); there's no way for the
|
||||
## data to point anywhere else.
|
||||
|
||||
var _catalog: Dictionary = {}
|
||||
var _loaded: bool = false
|
||||
var _catalog_path: String = "res://assets/scripting/spawn_catalog.json"
|
||||
|
||||
|
||||
## Load the catalog from disk. Call this before any lookups.
|
||||
func load_catalog(path: String = _catalog_path) -> Error:
|
||||
_catalog_path = path
|
||||
_catalog = {}
|
||||
|
||||
var file := FileAccess.open(path, FileAccess.READ)
|
||||
if file == null:
|
||||
return FileAccess.get_open_error()
|
||||
|
||||
var json_text: String = file.get_as_text()
|
||||
file.close()
|
||||
|
||||
var result: Variant = JSON.parse_string(json_text)
|
||||
if result == null or not (result is Dictionary) or not (result as Dictionary).has("templates"):
|
||||
return ERR_INVALID_DATA
|
||||
|
||||
_catalog = (result as Dictionary)["templates"]
|
||||
_loaded = true
|
||||
return OK
|
||||
|
||||
|
||||
func is_loaded() -> bool:
|
||||
return _loaded
|
||||
|
||||
|
||||
## Resolve a catalog_id to its template Dictionary ({} if unknown/unloaded).
|
||||
func resolve(catalog_id: String) -> Dictionary:
|
||||
if not _loaded:
|
||||
return {}
|
||||
return _catalog.get(catalog_id, {})
|
||||
|
||||
|
||||
func has_template(catalog_id: String) -> bool:
|
||||
return _loaded and _catalog.has(catalog_id)
|
||||
@@ -0,0 +1,462 @@
|
||||
extends SceneTree
|
||||
## Smoke test for the ScriptBehavior DSL + ScriptInterpreterNode.
|
||||
##
|
||||
## Run with:
|
||||
## godot --headless --path . --script res://scripts/smoke_test_script_behavior.gd
|
||||
##
|
||||
## Covers, in order:
|
||||
## 1. Parsing/validation: a well-formed behavior parses cleanly; malformed
|
||||
## or unsafe rules (unknown verb, unknown trigger, non-scalar
|
||||
## arguments meant to smuggle something unsafe, unknown condition
|
||||
## type/op) are rejected at parse time and never make it into
|
||||
## `rules` -- never partially applied.
|
||||
## 2. A behavior mixing one bad rule with one good rule in the same file:
|
||||
## the good rule still parses and still executes; the bad rule is
|
||||
## dropped, not silently run.
|
||||
## 3. The real demo wired into scenes/worlds/test_level.tscn
|
||||
## ("ScriptedChest"): loading scenes/game.tscn actually gets a
|
||||
## ScriptInterpreterNode with the demo behavior loaded, a Player with
|
||||
## a real Inventory, and pressing the real "interact" action while in
|
||||
## range actually runs give_item / play_sound / rotate -- proven by
|
||||
## observing the Inventory's item count change and the interpreter's
|
||||
## verb_executed signal, not by calling private methods directly.
|
||||
|
||||
const ScriptBehaviorClass := preload("res://scripts/scripting/script_behavior.gd")
|
||||
const ScriptInterpreterNodeClass := preload("res://scripts/scripting/script_interpreter.gd")
|
||||
const PlayerInventoryClass := preload("res://scripts/scripting/player_inventory.gd")
|
||||
const DynamicObjectNodeClass := preload("res://scripts/dynamic_object_node.gd")
|
||||
|
||||
var passed := 0
|
||||
var failed := 0
|
||||
|
||||
|
||||
func _initialize() -> void:
|
||||
_run()
|
||||
|
||||
|
||||
func _run() -> void:
|
||||
await process_frame
|
||||
|
||||
_test_valid_behavior_parses()
|
||||
_test_malformed_rules_are_rejected()
|
||||
_test_mixed_good_and_bad_rules()
|
||||
await _test_on_timer_trigger()
|
||||
_test_condition_gating()
|
||||
await _test_remaining_verbs()
|
||||
await _test_wired_demo_in_game_scene()
|
||||
|
||||
print("\n=== SMOKE RESULT: %d/%d passed ===" % [passed, passed + failed])
|
||||
quit(0 if failed == 0 else 1)
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 1. A well-formed behavior parses cleanly.
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
func _test_valid_behavior_parses() -> void:
|
||||
print("--- valid behavior parses cleanly ---")
|
||||
var data := {
|
||||
"rules": [
|
||||
{
|
||||
"trigger": {"type": "on_interact"},
|
||||
"conditions": [],
|
||||
"actions": [
|
||||
{"verb": "give_item", "item_id": "gold_coin", "count": 3},
|
||||
{"verb": "play_sound", "sound_id": "chime"},
|
||||
],
|
||||
}
|
||||
]
|
||||
}
|
||||
var behavior: ScriptBehaviorClass = ScriptBehaviorClass.load_from_dict(data)
|
||||
_check("valid behavior has exactly one rule", behavior.rules.size() == 1)
|
||||
_check("valid behavior has no rejected rules", behavior.rejected_rules.is_empty())
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 2. Malformed / unsafe rules never make it into `rules`.
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
func _test_malformed_rules_are_rejected() -> void:
|
||||
print("--- malformed/unsafe rules are safely rejected, not executed ---")
|
||||
|
||||
# Unknown verb -- e.g. an attempt to invoke something outside the
|
||||
# whitelist entirely.
|
||||
_expect_rejected("unknown verb", {
|
||||
"rules": [{
|
||||
"trigger": {"type": "on_interact"}, "conditions": [],
|
||||
"actions": [{"verb": "os_execute", "command": "rm -rf /"}],
|
||||
}]
|
||||
})
|
||||
|
||||
# Unknown trigger type.
|
||||
_expect_rejected("unknown trigger type", {
|
||||
"rules": [{
|
||||
"trigger": {"type": "on_explode"}, "conditions": [],
|
||||
"actions": [{"verb": "give_item", "item_id": "x", "count": 1}],
|
||||
}]
|
||||
})
|
||||
|
||||
# on_timer with a missing/invalid interval.
|
||||
_expect_rejected("on_timer missing interval", {
|
||||
"rules": [{
|
||||
"trigger": {"type": "on_timer"}, "conditions": [],
|
||||
"actions": [{"verb": "give_item", "item_id": "x", "count": 1}],
|
||||
}]
|
||||
})
|
||||
|
||||
# Attempt to smuggle a non-scalar (a nested object, the shape an
|
||||
# engine-reaching payload would need) as an item_id.
|
||||
_expect_rejected("non-scalar item_id", {
|
||||
"rules": [{
|
||||
"trigger": {"type": "on_interact"}, "conditions": [],
|
||||
"actions": [{"verb": "give_item", "item_id": {"call": "OS.execute"}, "count": 1}],
|
||||
}]
|
||||
})
|
||||
|
||||
# Negative/absurd count.
|
||||
_expect_rejected("out-of-range count", {
|
||||
"rules": [{
|
||||
"trigger": {"type": "on_interact"}, "conditions": [],
|
||||
"actions": [{"verb": "give_item", "item_id": "x", "count": -5}],
|
||||
}]
|
||||
})
|
||||
|
||||
# Invalid target (not "self"/"player").
|
||||
_expect_rejected("invalid move target", {
|
||||
"rules": [{
|
||||
"trigger": {"type": "on_interact"}, "conditions": [],
|
||||
"actions": [{"verb": "move", "target": "world_root", "offset": [0, 1, 0]}],
|
||||
}]
|
||||
})
|
||||
|
||||
# Unknown condition type/op.
|
||||
_expect_rejected("unknown condition type", {
|
||||
"rules": [{
|
||||
"trigger": {"type": "on_interact"},
|
||||
"conditions": [{"type": "player_health", "op": "==", "value": 100}],
|
||||
"actions": [{"verb": "give_item", "item_id": "x", "count": 1}],
|
||||
}]
|
||||
})
|
||||
_expect_rejected("unknown condition op", {
|
||||
"rules": [{
|
||||
"trigger": {"type": "on_interact"},
|
||||
"conditions": [{"type": "item_count", "item_id": "x", "op": "~=", "value": 1}],
|
||||
"actions": [{"verb": "give_item", "item_id": "x", "count": 1}],
|
||||
}]
|
||||
})
|
||||
|
||||
# Missing actions entirely.
|
||||
_expect_rejected("empty actions array", {
|
||||
"rules": [{"trigger": {"type": "on_interact"}, "conditions": [], "actions": []}]
|
||||
})
|
||||
|
||||
# No "rules" key at all.
|
||||
_expect_rejected("missing top-level rules key", {"not_rules": []})
|
||||
|
||||
|
||||
func _expect_rejected(label: String, data: Dictionary) -> void:
|
||||
var behavior: ScriptBehaviorClass = ScriptBehaviorClass.load_from_dict(data)
|
||||
_check("%s -> zero rules parsed" % label, behavior.rules.is_empty())
|
||||
_check("%s -> rejection reason recorded" % label, not behavior.rejected_rules.is_empty())
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 2b. A bad rule alongside a good rule in the SAME behavior: the good one
|
||||
# still parses and still runs; the bad one is dropped, not run "best
|
||||
# effort" and not blocking the good rule either.
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
func _test_mixed_good_and_bad_rules() -> void:
|
||||
print("--- one bad rule does not block or corrupt a sibling good rule ---")
|
||||
var data := {
|
||||
"rules": [
|
||||
{
|
||||
# Bad: unknown verb, should be dropped silently.
|
||||
"trigger": {"type": "on_interact"}, "conditions": [],
|
||||
"actions": [{"verb": "eval", "code": "OS.execute('id', [])"}],
|
||||
},
|
||||
{
|
||||
# Good: should parse and, when fired, actually run.
|
||||
"trigger": {"type": "on_interact"}, "conditions": [],
|
||||
"actions": [{"verb": "give_item", "item_id": "mixed_test_item", "count": 2}],
|
||||
},
|
||||
]
|
||||
}
|
||||
var behavior: ScriptBehaviorClass = ScriptBehaviorClass.load_from_dict(data)
|
||||
_check("mixed behavior kept only the good rule", behavior.rules.size() == 1)
|
||||
_check("mixed behavior recorded the bad rule's rejection", not behavior.rejected_rules.is_empty())
|
||||
|
||||
var interpreter := ScriptInterpreterNodeClass.new()
|
||||
interpreter.set_behavior(behavior)
|
||||
root.add_child(interpreter)
|
||||
|
||||
var fake_player := Node3D.new()
|
||||
fake_player.name = "FakePlayer"
|
||||
var inv := PlayerInventoryClass.new()
|
||||
inv.name = "Inventory"
|
||||
fake_player.add_child(inv)
|
||||
root.add_child(fake_player)
|
||||
|
||||
interpreter.fire("on_interact", fake_player)
|
||||
_check("the surviving good rule actually executed", inv.get_count("mixed_test_item") == 2)
|
||||
|
||||
interpreter.queue_free()
|
||||
fake_player.queue_free()
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 3b. on_timer actually fires on its own, with no player/interact/touch
|
||||
# involved at all -- driven purely by a real Timer node ticking down.
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
func _test_on_timer_trigger() -> void:
|
||||
print("--- on_timer fires repeatedly on its own ---")
|
||||
var data := {
|
||||
"rules": [{
|
||||
"trigger": {"type": "on_timer", "interval": 0.05},
|
||||
"conditions": [],
|
||||
"actions": [{"verb": "set_timer", "name": "ticked", "seconds": 60}],
|
||||
}]
|
||||
}
|
||||
var behavior: ScriptBehaviorClass = ScriptBehaviorClass.load_from_dict(data)
|
||||
_check("on_timer behavior parsed", behavior.rules.size() == 1)
|
||||
|
||||
var interpreter := ScriptInterpreterNodeClass.new()
|
||||
interpreter.set_behavior(behavior)
|
||||
root.add_child(interpreter)
|
||||
|
||||
# A plain int captured by a lambda is captured by value in GDScript
|
||||
# closures (the outer variable never sees the mutation) -- an Array's
|
||||
# *reference* is what gets captured, so appends are visible outside.
|
||||
var fire_log: Array = []
|
||||
interpreter.verb_executed.connect(func(_verb, _args): fire_log.append(true))
|
||||
|
||||
for i in 30:
|
||||
await physics_frame
|
||||
|
||||
_check("on_timer fired at least once with no trigger source but time",
|
||||
fire_log.size() >= 1)
|
||||
|
||||
interpreter.queue_free()
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 4. Conditions actually gate execution (not just parse).
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
func _test_condition_gating() -> void:
|
||||
print("--- conditions gate whether an action runs ---")
|
||||
var data := {
|
||||
"rules": [{
|
||||
"trigger": {"type": "on_interact"},
|
||||
"conditions": [{"type": "item_count", "item_id": "key", "op": ">=", "value": 1}],
|
||||
"actions": [{"verb": "give_item", "item_id": "treasure", "count": 1}],
|
||||
}]
|
||||
}
|
||||
var behavior: ScriptBehaviorClass = ScriptBehaviorClass.load_from_dict(data)
|
||||
_check("conditioned behavior parsed", behavior.rules.size() == 1)
|
||||
|
||||
var interpreter := ScriptInterpreterNodeClass.new()
|
||||
interpreter.set_behavior(behavior)
|
||||
root.add_child(interpreter)
|
||||
|
||||
var fake_player := Node3D.new()
|
||||
var inv := PlayerInventoryClass.new()
|
||||
inv.name = "Inventory"
|
||||
fake_player.add_child(inv)
|
||||
root.add_child(fake_player)
|
||||
|
||||
interpreter.fire("on_interact", fake_player)
|
||||
_check("condition not met -> action did not run", inv.get_count("treasure") == 0)
|
||||
|
||||
inv.give_item("key", 1)
|
||||
interpreter.fire("on_interact", fake_player)
|
||||
_check("condition met -> action ran", inv.get_count("treasure") == 1)
|
||||
|
||||
interpreter.queue_free()
|
||||
fake_player.queue_free()
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 2c. The remaining three verbs (move, spawn_from_catalog, set_timer) plus
|
||||
# the timer_active condition -- not exercised by the wired chest demo
|
||||
# (which only needs give_item/play_sound/rotate), so each gets a direct
|
||||
# check here that it actually does something real.
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
func _test_remaining_verbs() -> void:
|
||||
print("--- move / spawn_from_catalog / set_timer + timer_active condition ---")
|
||||
var data := {
|
||||
"rules": [
|
||||
{
|
||||
# Only grants the item while the "cooldown" timer is NOT
|
||||
# active -- proves timer_active is actually read back.
|
||||
"trigger": {"type": "on_interact"},
|
||||
"conditions": [{"type": "timer_active", "name": "cooldown", "op": "==", "value": false}],
|
||||
"actions": [{"verb": "give_item", "item_id": "cooldown_test_item", "count": 1}],
|
||||
},
|
||||
{
|
||||
"trigger": {"type": "on_interact"},
|
||||
"conditions": [],
|
||||
"actions": [
|
||||
{"verb": "set_timer", "name": "cooldown", "seconds": 10},
|
||||
{"verb": "move", "target": "self", "offset": [0, 0, -2], "duration": 0.2},
|
||||
{"verb": "spawn_from_catalog", "catalog_id": "small_crate", "position": [5, 0, 5]},
|
||||
],
|
||||
},
|
||||
]
|
||||
}
|
||||
var behavior: ScriptBehaviorClass = ScriptBehaviorClass.load_from_dict(data)
|
||||
_check("remaining-verbs behavior parsed with no rejections", behavior.rejected_rules.is_empty())
|
||||
|
||||
var interpreter := ScriptInterpreterNodeClass.new()
|
||||
interpreter.set_behavior(behavior)
|
||||
root.add_child(interpreter)
|
||||
var start_position: Vector3 = interpreter.position
|
||||
|
||||
var fake_player := Node3D.new()
|
||||
var inv := PlayerInventoryClass.new()
|
||||
inv.name = "Inventory"
|
||||
fake_player.add_child(inv)
|
||||
root.add_child(fake_player)
|
||||
|
||||
# First trigger: cooldown isn't active yet -> item granted, then the
|
||||
# second rule starts the cooldown timer and moves/spawns.
|
||||
interpreter.fire("on_interact", fake_player)
|
||||
_check("give_item ran while timer_active was false",
|
||||
inv.get_count("cooldown_test_item") == 1)
|
||||
|
||||
# Second trigger, same frame: set_timer's effect must already be
|
||||
# visible to a condition evaluated afterward -- this is the whole
|
||||
# point of the timer_active/timer_remaining state store existing.
|
||||
interpreter.fire("on_interact", fake_player)
|
||||
_check("give_item did NOT run again once the cooldown timer was active",
|
||||
inv.get_count("cooldown_test_item") == 1)
|
||||
|
||||
# move() animates over a real Tween, not a teleport -- wait it out.
|
||||
for i in 20:
|
||||
await physics_frame
|
||||
var moved: Vector3 = interpreter.position
|
||||
_check("move actually relocated the object (not instantly, via a Tween)",
|
||||
moved.distance_to(start_position + Vector3(0, 0, -2)) < 0.05)
|
||||
|
||||
# spawn_from_catalog should have added a real DynamicObjectNode sibling.
|
||||
var spawned: Node = null
|
||||
for child in root.get_children():
|
||||
if child is DynamicObjectNodeClass and (child as Node).name.begins_with("spawned_"):
|
||||
spawned = child
|
||||
_check("spawn_from_catalog actually added a DynamicObjectNode to the tree", spawned != null)
|
||||
if spawned != null:
|
||||
var dyn := spawned as DynamicObjectNodeClass
|
||||
_check("spawned object resolved asset_id via the trusted catalog (not the raw data)",
|
||||
dyn.world_object != null and dyn.world_object.asset_id == "props/crate_small.glb")
|
||||
_check("spawned object placed at the requested position",
|
||||
dyn.position.distance_to(Vector3(5, 0, 5)) < 0.01)
|
||||
spawned.queue_free()
|
||||
|
||||
interpreter.queue_free()
|
||||
fake_player.queue_free()
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 3. The real demo wired into the actual playable scene.
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
func _test_wired_demo_in_game_scene() -> void:
|
||||
print("--- real demo: ScriptedChest in scenes/worlds/test_level.tscn via scenes/game.tscn ---")
|
||||
|
||||
var packed: PackedScene = load("res://scenes/game.tscn")
|
||||
var result := change_scene_to_packed(packed)
|
||||
if not _check("game scene loaded", result == OK):
|
||||
return
|
||||
await scene_changed
|
||||
|
||||
var game: Node3D = current_scene as Node3D
|
||||
var player: Node = game.get_node_or_null("Player")
|
||||
if not _check("Player exists in loaded scene", player is CharacterBody3D):
|
||||
return
|
||||
|
||||
var inventory: Node = player.get_node_or_null("Inventory")
|
||||
if not _check("Player has a real Inventory node", inventory is PlayerInventoryClass):
|
||||
return
|
||||
|
||||
var chest: Node = game.get_node_or_null("Level/ScriptedChest")
|
||||
if not _check("ScriptedChest exists in the level", chest != null):
|
||||
return
|
||||
if not _check("ScriptedChest has the ScriptInterpreterNode script", chest is ScriptInterpreterNodeClass):
|
||||
return
|
||||
|
||||
var interpreter: ScriptInterpreterNodeClass = chest as ScriptInterpreterNodeClass
|
||||
# Let _ready() load the behavior and build its Area3D/timers.
|
||||
await process_frame
|
||||
_check("ScriptedChest's behavior loaded from disk", interpreter.behavior != null)
|
||||
if interpreter.behavior != null:
|
||||
_check("demo_chest.json parsed with no rejected rules",
|
||||
interpreter.behavior.rejected_rules.is_empty())
|
||||
|
||||
var executed_verbs: Array[String] = []
|
||||
interpreter.verb_executed.connect(func(verb, _args): executed_verbs.append(verb))
|
||||
|
||||
# Let physics settle: the player falls onto the ground and the
|
||||
# ScriptedChest's trigger Area3D needs a few physics frames to notice
|
||||
# the overlap before the interact key check has anyone "in range".
|
||||
for i in 60:
|
||||
await physics_frame
|
||||
|
||||
var before_count: int = (inventory as PlayerInventoryClass).get_count("gold_coin")
|
||||
var before_rot_y: float = interpreter.rotation_degrees.y
|
||||
|
||||
# A real input event, exactly like a player pressing E -- not a direct
|
||||
# call into the interpreter's action methods.
|
||||
var interact_event := InputEventKey.new()
|
||||
interact_event.keycode = KEY_E
|
||||
interact_event.physical_keycode = KEY_E
|
||||
interact_event.pressed = true
|
||||
Input.parse_input_event(interact_event)
|
||||
|
||||
for i in 10:
|
||||
await process_frame
|
||||
|
||||
var after_count: int = (inventory as PlayerInventoryClass).get_count("gold_coin")
|
||||
_check("pressing 'interact' near the chest granted gold_coin via give_item",
|
||||
after_count == before_count + 3)
|
||||
_check("give_item actually executed (verb_executed signal)", executed_verbs.has("give_item"))
|
||||
_check("play_sound actually executed (verb_executed signal)", executed_verbs.has("play_sound"))
|
||||
_check("rotate actually executed (verb_executed signal)", executed_verbs.has("rotate"))
|
||||
|
||||
# rotate animates over 0.4s via a real Tween -- wait it out, then check
|
||||
# the chest's rotation actually changed (not teleported instantly, but
|
||||
# not stuck at the start either).
|
||||
for i in 40:
|
||||
await physics_frame
|
||||
var after_rot_y: float = interpreter.rotation_degrees.y
|
||||
_check("rotate actually moved the chest's rotation",
|
||||
absf(wrapf(after_rot_y - before_rot_y - 90.0, -180.0, 180.0)) < 1.0)
|
||||
|
||||
# Pressing interact again with the player out of a fresh area-entry
|
||||
# state should still work (rule has no conditions/limits) -- give_item
|
||||
# is cumulative, proving repeated real triggers keep working.
|
||||
var interact_event2 := InputEventKey.new()
|
||||
interact_event2.keycode = KEY_E
|
||||
interact_event2.physical_keycode = KEY_E
|
||||
interact_event2.pressed = true
|
||||
Input.parse_input_event(interact_event2)
|
||||
for i in 10:
|
||||
await process_frame
|
||||
var final_count: int = (inventory as PlayerInventoryClass).get_count("gold_coin")
|
||||
_check("a second real interact press granted gold_coin again",
|
||||
final_count == after_count + 3)
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Helpers
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
func _check(description: String, condition: bool) -> bool:
|
||||
if condition:
|
||||
print(" PASS: ", description)
|
||||
passed += 1
|
||||
else:
|
||||
printerr(" FAIL: ", description)
|
||||
failed += 1
|
||||
return condition
|
||||
Reference in New Issue
Block a user