godot-mcp-tool 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 facelessdiplomat
+
+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.

package/README.md

@@ -1,3 +1,58 @@
-# Temporary Holding Version
+# godot-mcp-tool
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The MCP server and command-line tool of [Godot MCP Tool](https://github.com/facelessdiplomat/godot-mcp-tool). With
+it, Claude Code makes Godot 4 games through the Godot editor: it builds scenes that Ctrl+Z can undo, writes and checks
+GDScript, runs the game, plays input into it and reads its errors with stack traces.
+
+You need Godot 4.7 or newer, Node.js 22 or newer and Claude Code.
+
+## Quick start
+
+1. Install the editor addon into your Godot project. In the project folder, with the editor closed, run:
+
+   ```bash
+   npx godot-mcp-tool install-addon
+   ```
+
+2. Connect Claude Code. The Claude Code plugin is the best way: it also checks every GDScript file Claude writes.
+
+   ```bash
+   claude plugin marketplace add facelessdiplomat/godot-mcp-tool
+   claude plugin install godot@godot-mcp-tool
+   ```
+
+   Without the plugin, add the server to the project:
+
+   ```bash
+   claude mcp add --scope project godot -- npx -y godot-mcp-tool
+   ```
+
+3. Open the project in Godot, start `claude` in the project folder and ask: "Check the Godot connection."
+
+## Commands
+
+```text
+godot-mcp-tool                         Run the MCP server; Claude Code starts it
+godot-mcp-tool install-addon [folder]  Copy the addon into the Godot project and enable its plugin
+godot-mcp-tool update-addon [folder]   Replace the addon of the project with the version of this package
+godot-mcp-tool doctor [folder]         Check Node.js, Godot, the addon, the plugin and the connection to the editor
+godot-mcp-tool check-edited-script     Check the .gd file of a Claude Code hook input; the plugin's hook runs it
+```
+
+The folder is the Godot project: by default `GODOT_PROJECT_PATH`, or the current folder or the nearest folder above
+it that has a `project.godot`.
+
+## Documentation
+
+- [Setup guide](https://github.com/facelessdiplomat/godot-mcp-tool/blob/master/docs/setup.md): installing, connecting,
+  settings and troubleshooting.
+- [Usage guide](https://github.com/facelessdiplomat/godot-mcp-tool/blob/master/docs/usage.md): example requests,
+  safety and limitations.
+- [Tool reference](https://github.com/facelessdiplomat/godot-mcp-tool/blob/master/docs/tools.md): every tool with its
+  parameters.
+- [Security](https://github.com/facelessdiplomat/godot-mcp-tool/blob/master/SECURITY.md): how to report a problem and
+  how the tool protects your project.
+
+## License
+
+[MIT](https://github.com/facelessdiplomat/godot-mcp-tool/blob/master/LICENSE)

package/addon/godot_mcp_tool/addon_info.gd

@@ -0,0 +1,10 @@
+extends RefCounted
+
+const ADDON_VERSION := "0.1.0"
+const BRIDGE_PROTOCOL_VERSION := 1
+const DISCOVERY_RELATIVE_PATH := ".godot/godot_mcp_tool/bridge.json"
+const CAPTURES_RELATIVE_PATH := ".godot/godot_mcp_tool/captures"
+const LOOPBACK_ADDRESS := "127.0.0.1"
+const RUNTIME_AUTOLOAD_NAME := "GodotMcpRuntime"
+const SETTINGS_SECTION := "godot_mcp_tool"
+const UNSAFE_TOOLS_KEY := "allow_unsafe_tools"

package/addon/godot_mcp_tool/addon_info.gd.uid

@@ -0,0 +1 @@
+uid://cmkw424ct17bi

package/addon/godot_mcp_tool/animation/animation_reference.gd

@@ -0,0 +1,50 @@
+extends RefCounted
+
+const CommandError := preload("../commands/command_error.gd")
+const IndefiniteArticle := preload("../util/indefinite_article.gd")
+const JsonRpc := preload("../bridge/json_rpc.gd")
+const NodeFactory := preload("../scene/node_factory.gd")
+const NodeLocator := preload("../scene/node_locator.gd")
+
+const FORBIDDEN_NAME_CHARACTERS := ["/", ":", ",", "["]
+const LIBRARY_SEPARATOR := "/"
+
+var library_name := ""
+var animation_name := ""
+
+
+static func find_player(scene_root: Node, player_path: String) -> Variant:
+	var node := NodeLocator.find(scene_root, player_path)
+	if node == null:
+		return CommandError.new(JsonRpc.NOT_FOUND, "Node \"%s\" not found" % player_path, NodeLocator.not_found_hint(scene_root, player_path))
+	if not node is AnimationPlayer:
+		return CommandError.new(
+			JsonRpc.INVALID_PARAMS,
+			"%s is %s, not an AnimationPlayer" % [player_path, IndefiniteArticle.before(NodeFactory.display_class(node))],
+			"Add an AnimationPlayer with node_add; its tracks animate the nodes under its parent.",
+		)
+	return node
+
+
+static func parse(full_name: String) -> Variant:
+	var reference := new()
+	var name := full_name.strip_edges()
+	if name.contains(LIBRARY_SEPARATOR):
+		reference.library_name = name.get_slice(LIBRARY_SEPARATOR, 0)
+		name = name.substr(reference.library_name.length() + 1)
+	reference.animation_name = name
+	if name.is_empty() or FORBIDDEN_NAME_CHARACTERS.any(func(character: String) -> bool: return name.contains(character)) or _has_forbidden_character(reference.library_name):
+		return CommandError.new(
+			JsonRpc.INVALID_PARAMS,
+			"\"%s\" is not a valid animation name" % full_name,
+			"Animation names cannot be empty or contain / : , [; write \"library/name\" for an animation of another library than the default one.",
+		)
+	return reference
+
+
+static func _has_forbidden_character(library_name: String) -> bool:
+	return FORBIDDEN_NAME_CHARACTERS.any(func(character: String) -> bool: return library_name.contains(character))
+
+
+func full_name() -> String:
+	return animation_name if library_name.is_empty() else "%s%s%s" % [library_name, LIBRARY_SEPARATOR, animation_name]

package/addon/godot_mcp_tool/animation/animation_reference.gd.uid

@@ -0,0 +1 @@
+uid://deaayqfs2ns82

package/addon/godot_mcp_tool/animation/animation_report.gd

@@ -0,0 +1,48 @@
+extends RefCounted
+
+const AnimationVocabulary := preload("animation_vocabulary.gd")
+const VariantCodec := preload("../codec/variant_codec.gd")
+
+const MAXIMUM_KEYS_SHOWN := 20
+const DECIMAL_SCALE := 1000.0
+
+
+static func list(player: AnimationPlayer) -> Array:
+	var animations: Array = []
+	for name in player.get_animation_list():
+		var animation := player.get_animation(name)
+		animations.append({"name": str(name), "length": _rounded(animation.length), "loop": loop_name(animation), "tracks": animation.get_track_count()})
+	return animations
+
+
+static func detail(animation: Animation, name: String, codec: VariantCodec) -> Dictionary:
+	var tracks: Array = []
+	for index in animation.get_track_count():
+		tracks.append(_track(animation, index, codec))
+	return {"name": name, "length": _rounded(animation.length), "loop": loop_name(animation), "tracks": tracks}
+
+
+static func loop_name(animation: Animation) -> String:
+	return AnimationVocabulary.name_of(AnimationVocabulary.LOOP_MODES, animation.loop_mode)
+
+
+static func _track(animation: Animation, index: int, codec: VariantCodec) -> Dictionary:
+	var type := animation.track_get_type(index)
+	var track := {
+		"path": str(animation.track_get_path(index)),
+		"type": AnimationVocabulary.name_of(AnimationVocabulary.TRACK_TYPES, type),
+		"interpolation": AnimationVocabulary.name_of(AnimationVocabulary.INTERPOLATIONS, animation.track_get_interpolation_type(index)),
+	}
+	if type == Animation.TYPE_VALUE:
+		track["update"] = AnimationVocabulary.name_of(AnimationVocabulary.UPDATE_MODES, animation.value_track_get_update_mode(index))
+	var key_count := animation.track_get_key_count(index)
+	var keys: Array = []
+	for key_index in mini(key_count, MAXIMUM_KEYS_SHOWN):
+		keys.append({"time": _rounded(animation.track_get_key_time(index, key_index)), "value": codec.encode(animation.track_get_key_value(index, key_index))})
+	track["key_count"] = key_count
+	track["keys"] = keys
+	return track
+
+
+static func _rounded(value: float) -> float:
+	return roundf(value * DECIMAL_SCALE) / DECIMAL_SCALE

package/addon/godot_mcp_tool/animation/animation_report.gd.uid

@@ -0,0 +1 @@
+uid://dmelrjna2x0rf

package/addon/godot_mcp_tool/animation/animation_track_planner.gd

@@ -0,0 +1,188 @@
+extends RefCounted
+
+const AnimationVocabulary := preload("animation_vocabulary.gd")
+const NodeLocator := preload("../scene/node_locator.gd")
+const SimilarNames := preload("../util/similar_names.gd")
+const VariantCodec := preload("../codec/variant_codec.gd")
+
+const STEPPED_TYPES := [TYPE_BOOL, TYPE_STRING, TYPE_STRING_NAME, TYPE_NODE_PATH, TYPE_OBJECT]
+const DEFAULT_LENGTH := 1.0
+const DECIMAL_SCALE := 1000.0
+const RESET_LENGTH := 0.001
+
+var _codec: VariantCodec
+var _root: Node
+
+
+func _init(codec: VariantCodec, root: Node) -> void:
+	_codec = codec
+	_root = root
+
+
+func plan(track_descriptions: Array, requested_length: Variant) -> Dictionary:
+	var planned: Array = []
+	var rejected: Array = []
+	var used_paths: Array = []
+	for index in track_descriptions.size():
+		var description: Variant = track_descriptions[index]
+		var path := str(description.get("path", "")) if description is Dictionary else ""
+		var track: Variant = _plan_track(description)
+		if track is String:
+			rejected.append({"index": index, "path": path, "reason": track})
+			continue
+		if path in used_paths:
+			rejected.append({"index": index, "path": path, "reason": "this track is given twice; give each property one track with all its keys"})
+			continue
+		used_paths.append(path)
+		track["index"] = index
+		planned.append(track)
+	var length: float = requested_length if requested_length != null else _last_key_time(planned)
+	var within_length: Array = []
+	for track in planned:
+		var late_key := _first_key_after(track, length)
+		if late_key >= 0.0:
+			var reason := "the key at %s s is after the end of the animation at %s s; make the animation longer with length" % [_seconds(late_key), _seconds(length)]
+			rejected.append({"index": track["index"], "path": track["path"], "reason": reason})
+			continue
+		within_length.append(track)
+	rejected.sort_custom(func(left: Dictionary, right: Dictionary) -> bool: return left["index"] < right["index"])
+	var rejections := rejected.map(func(rejection: Dictionary) -> Dictionary: return {"path": rejection["path"], "reason": rejection["reason"]})
+	return {"tracks": within_length, "rejected": rejections, "length": length}
+
+
+func build(planned_tracks: Array, length: float, loop_mode: int) -> Animation:
+	var animation := Animation.new()
+	animation.length = length
+	animation.loop_mode = loop_mode
+	for track in planned_tracks:
+		var index := animation.add_track(Animation.TYPE_VALUE)
+		animation.track_set_path(index, NodePath(track["path"]))
+		animation.track_set_interpolation_type(index, track["interpolation"])
+		animation.value_track_set_update_mode(index, track["update"])
+		for key in track["keys"]:
+			animation.track_insert_key(index, key["time"], key["value"])
+	return animation
+
+
+func build_reset(previous: Animation, planned_tracks: Array) -> Animation:
+	var reset := previous.duplicate() as Animation if previous != null else Animation.new()
+	if previous == null:
+		reset.length = RESET_LENGTH
+	for track in planned_tracks:
+		var index := reset.add_track(Animation.TYPE_VALUE)
+		reset.track_set_path(index, NodePath(track["path"]))
+		reset.track_set_interpolation_type(index, track["interpolation"])
+		reset.value_track_set_update_mode(index, track["update"])
+		reset.track_insert_key(index, 0.0, current_value(track))
+	return reset
+
+
+func current_value(track: Dictionary) -> Variant:
+	var path := str(track["path"])
+	var node_part := path.get_slice(":", 0)
+	return _root.get_node(NodePath(node_part)).get_indexed(NodePath(":" + path.substr(node_part.length() + 1)))
+
+
+func describe(track: Dictionary) -> Dictionary:
+	var keys: Array = track["keys"]
+	return {
+		"path": track["path"],
+		"keys": keys.size(),
+		"interpolation": AnimationVocabulary.name_of(AnimationVocabulary.INTERPOLATIONS, track["interpolation"]),
+		"update": AnimationVocabulary.name_of(AnimationVocabulary.UPDATE_MODES, track["update"]),
+		"from": _codec.encode(keys.front()["value"]),
+		"to": _codec.encode(keys.back()["value"]),
+	}
+
+
+func _plan_track(description: Variant) -> Variant:
+	if not description is Dictionary:
+		return "a track is an object such as {\"path\": \"Door:position\", \"keys\": [{\"time\": 0, \"value\": [0, 0, 0]}]}"
+	var path := str(description.get("path", ""))
+	var node_part := path.get_slice(":", 0)
+	var property_path := path.substr(node_part.length() + 1) if path.contains(":") else ""
+	if node_part.is_empty() or property_path.is_empty():
+		return "track paths are Node:property relative to the parent of the AnimationPlayer, such as \"Door:position\" or \".:visible\""
+	var target := _root.get_node_or_null(NodePath(node_part))
+	if target == null:
+		return "there is no node %s under %s. %s" % [node_part, _root.name, NodeLocator.not_found_hint(_root, node_part)]
+	var property: Variant = _property_of(target, property_path)
+	if property is String:
+		return property
+	var interpolation: Variant = _named_value(description, "interpolation", AnimationVocabulary.INTERPOLATIONS, "linear")
+	if interpolation is String:
+		return interpolation
+	var default_update := "discrete" if _is_stepped(property) else "continuous"
+	var update: Variant = _named_value(description, "update", AnimationVocabulary.UPDATE_MODES, default_update)
+	if update is String:
+		return update
+	var keys: Variant = _decode_keys(description.get("keys", []), property, target, property_path)
+	if keys is String:
+		return keys
+	return {"path": path, "interpolation": interpolation, "update": update, "keys": keys}
+
+
+func _property_of(target: Node, property_path: String) -> Variant:
+	var property_name := property_path.get_slice(":", 0)
+	var properties := {}
+	for property in target.get_property_list():
+		properties[str(property["name"])] = property
+	if not properties.has(property_name):
+		var similar := SimilarNames.hint(property_name, properties.keys())
+		return "%s has no property \"%s\"%s" % [target.name, property_name, "" if similar.is_empty() else ". " + similar]
+	if property_path == property_name:
+		return properties[property_name]
+	var current: Variant = target.get_indexed(NodePath(":" + property_path))
+	if current == null:
+		return "%s has no part \"%s\"" % [target.name, property_path]
+	return {"name": property_path, "type": typeof(current), "hint": PROPERTY_HINT_NONE, "hint_string": "", "usage": PROPERTY_USAGE_DEFAULT}
+
+
+func _decode_keys(key_descriptions: Variant, property: Dictionary, target: Node, property_path: String) -> Variant:
+	if not key_descriptions is Array or (key_descriptions as Array).is_empty():
+		return "a track needs keys, such as [{\"time\": 0, \"value\": [0, 0, 0]}, {\"time\": 1, \"value\": [0, 3, 0]}]"
+	var keys: Array = []
+	for key_description in key_descriptions:
+		if not key_description is Dictionary or not (key_description.get("time") is int or key_description.get("time") is float) or float(key_description["time"]) < 0.0:
+			return "each key is {\"time\": seconds from 0, \"value\": ...}"
+		if not key_description.has("value"):
+			return "the key at %s s has no value" % _seconds(key_description["time"])
+		var outcome := _codec.decode(key_description["value"], property, target)
+		if not outcome.is_success:
+			return "%s at %s s: %s" % [property_path, _seconds(key_description["time"]), outcome.error]
+		keys.append({"time": float(key_description["time"]), "value": outcome.value})
+	keys.sort_custom(func(left: Dictionary, right: Dictionary) -> bool: return left["time"] < right["time"])
+	return keys
+
+
+static func _named_value(description: Dictionary, key: String, names: Dictionary, default_name: String) -> Variant:
+	var name: Variant = description.get(key, default_name)
+	var value: Variant = AnimationVocabulary.value_of(names, name)
+	if value == null:
+		return "unknown %s \"%s\"; use one of: %s" % [key, name, AnimationVocabulary.listed(names)]
+	return value
+
+
+static func _is_stepped(property: Dictionary) -> bool:
+	if property["type"] in STEPPED_TYPES:
+		return true
+	return property["type"] == TYPE_INT and property.get("hint") == PROPERTY_HINT_ENUM
+
+
+static func _last_key_time(tracks: Array) -> float:
+	var last := 0.0
+	for track in tracks:
+		last = maxf(last, (track["keys"] as Array).back()["time"])
+	return last if last > 0.0 else DEFAULT_LENGTH
+
+
+static func _first_key_after(track: Dictionary, length: float) -> float:
+	for key in track["keys"]:
+		if key["time"] > length + 0.0001:
+			return key["time"]
+	return -1.0
+
+
+static func _seconds(value: Variant) -> String:
+	var rounded := roundf(float(value) * DECIMAL_SCALE) / DECIMAL_SCALE
+	return str(roundi(rounded)) if is_equal_approx(rounded, roundf(rounded)) else str(rounded)

package/addon/godot_mcp_tool/animation/animation_track_planner.gd.uid

@@ -0,0 +1 @@
+uid://x5xohexuoo0t

package/addon/godot_mcp_tool/animation/animation_vocabulary.gd

@@ -0,0 +1,50 @@
+extends RefCounted
+
+const INTERPOLATIONS := {
+	"nearest": Animation.INTERPOLATION_NEAREST,
+	"linear": Animation.INTERPOLATION_LINEAR,
+	"cubic": Animation.INTERPOLATION_CUBIC,
+	"linear_angle": Animation.INTERPOLATION_LINEAR_ANGLE,
+	"cubic_angle": Animation.INTERPOLATION_CUBIC_ANGLE,
+}
+
+const UPDATE_MODES := {
+	"continuous": Animation.UPDATE_CONTINUOUS,
+	"discrete": Animation.UPDATE_DISCRETE,
+	"capture": Animation.UPDATE_CAPTURE,
+}
+
+const LOOP_MODES := {
+	"none": Animation.LOOP_NONE,
+	"linear": Animation.LOOP_LINEAR,
+	"pingpong": Animation.LOOP_PINGPONG,
+}
+
+const TRACK_TYPES := {
+	"value": Animation.TYPE_VALUE,
+	"position_3d": Animation.TYPE_POSITION_3D,
+	"rotation_3d": Animation.TYPE_ROTATION_3D,
+	"scale_3d": Animation.TYPE_SCALE_3D,
+	"blend_shape": Animation.TYPE_BLEND_SHAPE,
+	"method": Animation.TYPE_METHOD,
+	"bezier": Animation.TYPE_BEZIER,
+	"audio": Animation.TYPE_AUDIO,
+	"animation": Animation.TYPE_ANIMATION,
+}
+
+
+static func name_of(names: Dictionary, value: int) -> String:
+	for name in names:
+		if names[name] == value:
+			return name
+	return str(value)
+
+
+static func value_of(names: Dictionary, name: Variant) -> Variant:
+	if not name is String:
+		return null
+	return names.get((name as String).to_lower(), null)
+
+
+static func listed(names: Dictionary) -> String:
+	return ", ".join(PackedStringArray(names.keys()))

package/addon/godot_mcp_tool/animation/animation_vocabulary.gd.uid

@@ -0,0 +1 @@
+uid://c0ybwpwuqs80q

package/addon/godot_mcp_tool/animation/state_machine_plan.gd

@@ -0,0 +1,157 @@
+extends RefCounted
+
+const SimilarNames := preload("../util/similar_names.gd")
+
+const START := "Start"
+const END := "End"
+const SWITCH_MODES := {
+	"immediate": AnimationNodeStateMachineTransition.SWITCH_MODE_IMMEDIATE,
+	"sync": AnimationNodeStateMachineTransition.SWITCH_MODE_SYNC,
+	"at_end": AnimationNodeStateMachineTransition.SWITCH_MODE_AT_END,
+}
+const ADVANCE_MODES := {
+	"disabled": AnimationNodeStateMachineTransition.ADVANCE_MODE_DISABLED,
+	"enabled": AnimationNodeStateMachineTransition.ADVANCE_MODE_ENABLED,
+	"auto": AnimationNodeStateMachineTransition.ADVANCE_MODE_AUTO,
+}
+const MAXIMUM_PRIORITY := 32
+const STATES_PER_ROW := 4
+const FIRST_STATE_POSITION := Vector2(200, 250)
+const STATE_SPACING := Vector2(200, 150)
+
+var states: Array = []
+var transitions: Array = []
+var rejected: Array = []
+var warnings: Array = []
+var _player: AnimationPlayer
+var _condition_pattern := RegEx.create_from_string("^[A-Za-z_][A-Za-z0-9_]*$")
+
+
+func _init(player: AnimationPlayer) -> void:
+	_player = player
+
+
+func plan(state_descriptions: Array, transition_descriptions: Array) -> void:
+	for description in state_descriptions:
+		_plan_state(description)
+	for description in transition_descriptions:
+		_plan_transition(description)
+	if not states.is_empty() and not transitions.any(func(transition: Dictionary) -> bool: return transition["from"] == START):
+		warnings.append("no transition leaves Start, so the tree plays nothing until a script calls travel() or start() on parameters/playback; add one such as {\"from\": \"Start\", \"to\": \"%s\"}" % states[0]["name"])
+
+
+func build() -> AnimationNodeStateMachine:
+	var machine := AnimationNodeStateMachine.new()
+	for index in states.size():
+		var node := AnimationNodeAnimation.new()
+		node.animation = states[index]["animation"]
+		var grid_cell := Vector2(index % STATES_PER_ROW, index / STATES_PER_ROW)
+		machine.add_node(states[index]["name"], node, FIRST_STATE_POSITION + grid_cell * STATE_SPACING)
+	for planned in transitions:
+		var transition := AnimationNodeStateMachineTransition.new()
+		transition.advance_mode = ADVANCE_MODES[planned["advance"]]
+		transition.switch_mode = SWITCH_MODES[planned["switch"]]
+		transition.xfade_time = planned["xfade"]
+		transition.advance_condition = planned.get("condition", "")
+		transition.advance_expression = planned.get("expression", "")
+		transition.priority = planned.get("priority", 1)
+		machine.add_transition(planned["from"], planned["to"], transition)
+	return machine
+
+
+func _plan_state(description: Variant) -> void:
+	if not description is Dictionary or not description.get("name") is String or not description.get("animation") is String:
+		rejected.append({"item": str(description), "reason": "a state is {\"name\": \"walk\", \"animation\": \"walk\"}"})
+		return
+	var name: String = description["name"]
+	var animation: String = description["animation"]
+	var reason := ""
+	if name.is_empty() or name.contains("/"):
+		reason = "state names cannot be empty or contain /"
+	elif name == START or name == END:
+		reason = "%s and %s are the built-in entry and exit of every state machine; give the state another name" % [START, END]
+	elif states.any(func(state: Dictionary) -> bool: return state["name"] == name):
+		reason = "this state is given twice"
+	elif not _player.has_animation(animation):
+		var known := Array(_player.get_animation_list()).map(func(animation_name: StringName) -> String: return str(animation_name))
+		var similar := SimilarNames.hint(animation, known)
+		reason = "%s has no animation \"%s\"%s" % [_player.name, animation, "" if similar.is_empty() else ". " + similar]
+	if not reason.is_empty():
+		rejected.append({"item": name, "reason": reason})
+		return
+	states.append({"name": name, "animation": animation})
+
+
+func _plan_transition(description: Variant) -> void:
+	if not description is Dictionary or not description.get("from") is String or not description.get("to") is String:
+		rejected.append({"item": str(description), "reason": "a transition is {\"from\": \"idle\", \"to\": \"walk\"}"})
+		return
+	var from: String = description["from"]
+	var to: String = description["to"]
+	var label := "%s -> %s" % [from, to]
+	var planned: Variant = _transition(description, from, to)
+	if planned is String:
+		rejected.append({"item": label, "reason": planned})
+		return
+	transitions.append(planned)
+
+
+func _transition(description: Dictionary, from: String, to: String) -> Variant:
+	if from == END:
+		return "no transition can leave %s" % END
+	if to == START:
+		return "no transition can enter %s" % START
+	if from == to:
+		return "a state cannot have a transition to itself"
+	for state_name in [from, to]:
+		if not _is_known_state(state_name):
+			return "there is no state %s. %s" % [state_name, SimilarNames.hint(state_name, _state_names())]
+	if transitions.any(func(transition: Dictionary) -> bool: return transition["from"] == from and transition["to"] == to):
+		return "this transition is given twice"
+	var planned := {"from": from, "to": to}
+	var condition: Variant = description.get("condition")
+	if condition != null:
+		if not condition is String or not _condition_pattern.search(condition):
+			return "the condition \"%s\" is not a valid name; use letters, digits and _, such as moving" % condition
+		planned["condition"] = condition
+	var expression: Variant = description.get("expression")
+	if expression != null:
+		var parsed := Expression.new()
+		if not expression is String or parsed.parse(expression) != OK:
+			return "the expression \"%s\" does not parse: %s" % [expression, parsed.get_error_text()]
+		planned["expression"] = expression
+	var default_advance := "auto" if from == START or planned.has("condition") or planned.has("expression") else "enabled"
+	var advance: Variant = description.get("advance", default_advance)
+	if not advance in ADVANCE_MODES:
+		return "unknown advance \"%s\"; use one of: %s" % [advance, ", ".join(PackedStringArray(ADVANCE_MODES.keys()))]
+	var switch: Variant = description.get("switch", "immediate")
+	if not switch in SWITCH_MODES:
+		return "unknown switch \"%s\"; use one of: %s" % [switch, ", ".join(PackedStringArray(SWITCH_MODES.keys()))]
+	var xfade: Variant = description.get("xfade", 0.0)
+	if not (xfade is int or xfade is float) or float(xfade) < 0.0:
+		return "xfade is the cross-fade time in seconds, 0 or more"
+	planned["advance"] = advance
+	planned["switch"] = switch
+	planned["xfade"] = float(xfade)
+	var priority: Variant = description.get("priority")
+	if priority != null:
+		if not (priority is int or priority is float) or int(priority) < 0 or int(priority) > MAXIMUM_PRIORITY:
+			return "priority is a whole number from 0 to %d; lower numbers win" % MAXIMUM_PRIORITY
+		planned["priority"] = int(priority)
+	return _ordered(planned)
+
+
+func _is_known_state(state_name: String) -> bool:
+	return state_name == START or state_name == END or states.any(func(state: Dictionary) -> bool: return state["name"] == state_name)
+
+
+func _state_names() -> Array:
+	return [START, END] + states.map(func(state: Dictionary) -> String: return state["name"])
+
+
+static func _ordered(planned: Dictionary) -> Dictionary:
+	var ordered := {"from": planned["from"], "to": planned["to"], "advance": planned["advance"], "switch": planned["switch"], "xfade": planned["xfade"]}
+	for optional in ["condition", "expression", "priority"]:
+		if planned.has(optional):
+			ordered[optional] = planned[optional]
+	return ordered

package/addon/godot_mcp_tool/animation/state_machine_plan.gd.uid

@@ -0,0 +1 @@
+uid://bgf2wtiyqaon4