Fullwall: /* Behaviors */

2025-12-01T18:55:48Z

Behaviors

Fullwall: /* Tree Structure */

2025-12-01T18:53:18Z

Tree Structure

← Older revision		Revision as of 18:53, 1 December 2025
Line 7:		Line 7:
	All behavior trees start with a <code>tree:</code> root node:		All behavior trees start with a <code>tree:</code> root node:

	~~```~~yaml		{{codebox\|height=200px\|width=100%\|\|<pre lang="yaml">
	tree:		tree:
	sequence:		sequence:
	- behavior_name arg1 arg2		- behavior_name arg1 arg2
	- another_behavior		- another_behavior
	~~```~~		</pre>}}

	== Built-in Types ==		== Built-in Types ==

Fullwall: /* Tree Structure */

2025-12-01T18:51:37Z

Tree Structure

← Older revision		Revision as of 18:51, 1 December 2025
Line 7:		Line 7:
	All behavior trees start with a <code>tree:</code> root node:		All behavior trees start with a <code>tree:</code> root node:

	`yaml		```yaml
	tree:		tree:
	sequence:		sequence:
	- behavior_name arg1 arg2		- behavior_name arg1 arg2
	- another_behavior		- another_behavior
	`		```

	== Built-in Types ==		== Built-in Types ==

Fullwall: /* Tree Structure */

2025-12-01T18:51:28Z

Tree Structure

← Older revision		Revision as of 18:51, 1 December 2025
Line 7:		Line 7:
	All behavior trees start with a <code>tree:</code> root node:		All behavior trees start with a <code>tree:</code> root node:

	~~<syntaxhighlight lang="~~yaml">		`yaml
	tree:		tree:
	sequence:		sequence:
	- behavior_name arg1 arg2		- behavior_name arg1 arg2
	- another_behavior		- another_behavior
	~~</syntaxhighlight>~~		`

	== Built-in Types ==		== Built-in Types ==

Fullwall: Created page with "= Behaviors = The Behaviors system allows NPCs to run AI behaviors defined in YAML format. Behaviors can be simple actions like walking or waiting, or complex sequences with conditions, loops, and parallel execution. == Tree Structure == All behavior trees start with a `tree:` root node: tree: sequence: - behavior_name arg1 arg2 - another_behavior == Built-in Types == === sequence === Runs child..."

2025-12-01T18:51:13Z

Created page with "= Behaviors = The Behaviors system allows NPCs to run AI behaviors defined in YAML format. Behaviors can be simple actions like walking or waiting, or complex sequences with conditions, loops, and parallel execution. == Tree Structure == All behavior trees start with a <code>tree:</code> root node: <syntaxhighlight lang="yaml"> tree: sequence: - behavior_name arg1 arg2 - another_behavior </syntaxhighlight> == Built-in Types == === sequence === Runs child..."

New page

= Behaviors =

The Behaviors system allows NPCs to run AI behaviors defined in YAML format. Behaviors can be simple actions like walking or waiting, or complex sequences with conditions, loops, and parallel execution.

== Tree Structure ==

All behavior trees start with a <code>tree:</code> root node:

<syntaxhighlight lang="yaml">
tree:
sequence:
- behavior_name arg1 arg2
- another_behavior
</syntaxhighlight>

== Built-in Types ==

=== sequence ===

Runs children in order until one fails.

<syntaxhighlight lang="yaml">
tree:
sequence:
- say "First"
- wait 1s
- say "Second"
</syntaxhighlight>

=== selector / random ===

Runs one sub-behavior at random.
<syntaxhighlight lang="yaml">
tree:
selector:
- sequence:
- if `player_nearby`:
- say "I see you!"
- wander radius=15
</syntaxhighlight>

=== parallel ===
Runs multiple behaviors at the same time.

<syntaxhighlight lang="yaml">
tree:
parallel:
- wander radius=10 pathfind=true
- sequence:
- wait 5s
- say "Still wandering..."
</syntaxhighlight>

=== loop [condition] ===

Runs the children in sequence if the condition is true.

<syntaxhighlight lang="yaml">
tree:
loop `memory.get('counter', 0) < 5`:
- say "Count is {memory.get('counter', 0)}"
- set counter `memory.get('counter', 0) + 1`
- wait 1s
</syntaxhighlight>

=== if [condition] / else ===

<syntaxhighlight lang="yaml">
tree:
sequence:
- if `memory.has('greeted')`:
- say "Welcome back!"
else:
- say "Nice to meet you!"
- set greeted true
</syntaxhighlight>

=== invert ===

Inverts the success or failure of its child.

<syntaxhighlight lang="yaml">
tree:
invert:
- fail
</syntaxhighlight>

=== timeout [duration] ===

If the child doesn't complete within the specified duration, it fails.

<syntaxhighlight lang="yaml">
tree:
timeout 5s:
- walkto 500 64 500
</syntaxhighlight>

=== eval [language] ===

Evaluates multiple expressions.

<syntaxhighlight lang="yaml">
tree:
eval:
- memory.set('x', 100)
- memory.set('y', 64)
- memory.set('z', 200)
</syntaxhighlight>

Or with a specific language (javascript, molang):

<syntaxhighlight lang="yaml">
tree:
eval molang:
- v.test = 5
- v.result = v.test * 2
</syntaxhighlight>

=== Movement ===

==== walkto ====

Walks to specified coordinates.

'''Inline usage:'''
<syntaxhighlight lang="yaml">
- walkto 100 64 200 speed=1.5 range=50
</syntaxhighlight>

'''Named parameters:'''
<syntaxhighlight lang="yaml">
- walkto:
x: 100
y: 64
z: 200
speed: 1.5
range: 50
distance_margin: 2
</syntaxhighlight>

'''Parameters:'''
* <code>x</code>, <code>y</code>, <code>z</code> - Target coordinates (required)
* <code>speed</code> - Movement speed multiplier (optional)
* <code>range</code> - Maximum pathfinding range (optional)
* <code>distance_margin</code> / <code>margin</code> - How close in blocks to get to target (optional)

==== wander ====

Random wandering within a radius.

<syntaxhighlight lang="yaml">
- wander radius=10 pathfind=true
</syntaxhighlight>

'''Parameters:'''
* <code>radius</code> - Wander radius in blocks (default: 10)
* <code>pathfind</code> - Whether to use pathfinding (default: true)

==== look ====

Makes the NPC look at specific coordinates.

<syntaxhighlight lang="yaml">
- look 100 64 200
</syntaxhighlight>

'''Parameters:'''
* <code>x</code>, <code>y</code>, <code>z</code> - Target coordinates (required)

==== teleport ====

Teleports the NPC to coordinates.

<syntaxhighlight lang="yaml">
- teleport 100 64 200
- teleport 100 64 200 world_name
</syntaxhighlight>

'''Parameters:'''
* <code>x</code>, <code>y</code>, <code>z</code> - Target coordinates (required)
* <code>world</code> - World name (optional, defaults to current world)

=== Timing ===

==== wait ====

Waits for a specified duration.

<syntaxhighlight lang="yaml">
- wait 3s # 3 seconds
- wait 100t # 100 ticks
- wait 2m # 2 minutes
</syntaxhighlight>

'''Duration formats:'''
* <code>s</code> - seconds
* <code>t</code> - ticks
* <code>m</code> - minutes
* Can also use expressions: <code>wait `some_expression`</code>

==== wait_until ====

Waits until a condition becomes true.

<syntaxhighlight lang="yaml">
- wait_until `player.distance < 10`
</syntaxhighlight>

==== cooldown ====

Rate limits behaviors. Only succeeds if enough time has passed since the last time it was run.

<syntaxhighlight lang="yaml">
- cooldown greeting 30s
- say "Hello there!"
</syntaxhighlight>

'''Parameters:'''
* <code>key</code> - Cooldown identifier (required)
* <code>duration</code> - Cooldown duration (default: 1s)

=== Memory Management ===

==== set ====

Sets a memory variable.

<syntaxhighlight lang="yaml">
- set counter 5
- set name "Bob"
- set calculated `10 * 5`
</syntaxhighlight>

'''Parameters:'''
* <code>key</code> - Variable name (required)
* <code>value</code> - Value to set (required, can be expression)

==== forget ====

Removes a memory variable.

<syntaxhighlight lang="yaml">
- forget counter
</syntaxhighlight>

==== clear_memory ====

Clears all memory variables.

<syntaxhighlight lang="yaml">
- clear_memory
</syntaxhighlight>

=== Communication ===

==== say ====

Makes the NPC say a message to nearby players.

<syntaxhighlight lang="yaml">
- say "Hello, world!"
- say `"Player count: " + player.count`
</syntaxhighlight>

==== emit_signal ====

Emits a signal.

<syntaxhighlight lang="yaml">
- emit_signal "start_patrol"
</syntaxhighlight>

==== emit_signal_to ====

Emits a signal to a specific NPC by ID or UUID.

<syntaxhighlight lang="yaml">
- emit_signal_to 123 "alert"
- emit_signal_to "uuid-string" "alert"
</syntaxhighlight>

'''Parameters:'''
* <code>npc</code> - NPC ID or UUID (required)
* <code>signal</code> - Signal name (required)

==== emit_global_signal ====

Emits a signal that all NPCs receive.

<syntaxhighlight lang="yaml">
- emit_global_signal "server_restart_warning"
</syntaxhighlight>

==== wait_for_signal ====

Waits until a signal is received.

<syntaxhighlight lang="yaml">
- wait_for_signal "start_patrol"
- say "Signal received!"
</syntaxhighlight>

=== World Interaction ===

==== break_block ====

Breaks a block realistically using the NPC's held item at the specified coordinates.

<syntaxhighlight lang="yaml">
- break_block 100 64 200 radius=3
</syntaxhighlight>

'''Parameters:'''
* <code>x</code>, <code>y</code>, <code>z</code> - Block coordinates (required)
* <code>radius</code> - Maximum distance in blocks to break from (default: 3)

=== Control Flow ===

==== succeed ====

Always returns SUCCESS.

<syntaxhighlight lang="yaml">
- succeed
</syntaxhighlight>

==== fail ====

Always returns FAILURE.

<syntaxhighlight lang="yaml">
- fail
</syntaxhighlight>

==== repeat ====

Repeats a specified number of times.

<syntaxhighlight lang="yaml">
- repeat 5:
- say "Counting..."
- wait 1s
</syntaxhighlight>

'''Parameters:'''
* <code>count</code> - Number of repetitions (default: 1)

== Special Syntax ==

=== Command Execution ===

Lines starting with <code>/</code> are executed as commands:

<syntaxhighlight lang="yaml">
tree:
sequence:
- /npc speak "Hello from command!"
- /say This is a server command
</syntaxhighlight>

=== Expression Evaluation ===

Lines starting with backtick (<code>`</code>) are evaluated as expressions:

<syntaxhighlight lang="yaml">
tree:
sequence:
- `inv.add(item.json('{"material":"DIAMOND","amount":64}'))`
- `memory.set('flag', true)`
</syntaxhighlight>

== Expression System ==

The behavior tree system integrates with the Expression Registry for dynamic values.

=== Expression Syntax ===

Expressions can be used in several ways:

'''Inline in conditions:'''
<syntaxhighlight lang="yaml">
- if `memory.get('counter') < 10`:
- say "Counter is low"
</syntaxhighlight>

'''In parameter values:'''
<syntaxhighlight lang="yaml">
- walkto `npc.location.x + 10` `npc.location.y` `npc.location.z`
</syntaxhighlight>

'''In text:'''
<syntaxhighlight lang="yaml">
- say "Counter value: {memory.get('counter')}"
</syntaxhighlight>

'''Standalone evaluation:'''
<syntaxhighlight lang="yaml">
- `memory.set('result', 10 * 5)`
</syntaxhighlight>

== Memory System ==

The memory system provides persistent storage across behavior executions.

=== Usage ===

<syntaxhighlight lang="yaml">
tree:
sequence:
- set visited_waypoint_1 true
- set visit_count `memory.get('visit_count', 0) + 1`
- if `memory.has('greeted')`:
- say "Welcome back! Visit #{memory.get('visit_count')}"
else:
- say "First visit!"
- set greeted true
- forget temporary_flag
</syntaxhighlight>

=== Memory Methods ===

* <code>memory.set(key, value)</code> - Set a value
* <code>memory.get(key, default)</code> - Get a value with optional default
* <code>memory.has(key)</code> - Check if key exists
* <code>memory.remove(key)</code> - Remove a key
* <code>memory.clear()</code> - Clear all memory

Memory is automatically saved and loaded with the NPC.

== Complete Examples ==

=== Basic Patrol ===

<syntaxhighlight lang="yaml">
tree:
sequence:
- set patrol_started true
- loop `memory.get('patrol_count', 0) < 3`:
- walkto `npc.location.x + 10` `npc.location.y` `npc.location.z`
- wait 2s
- cooldown speak 10s
- say "Patrolling area {memory.get('patrol_count', 0)}"
- walkto `npc.location.x - 10` `npc.location.y` `npc.location.z`
- set patrol_count `memory.get('patrol_count', 0) + 1`
- say "Patrol complete!"
- forget patrol_count
</syntaxhighlight>

=== Signal Coordination ===

'''Guard NPC:'''
<syntaxhighlight lang="yaml">
tree:
sequence:
- wait_for_signal "intruder_alert"
- say "Intruder detected! Responding!"
- walkto `signal.data.x` `signal.data.y` `signal.data.z`
- emit_global_signal "area_secured"
</syntaxhighlight>

'''Lookout NPC:'''
<syntaxhighlight lang="yaml">
tree:
sequence:
- if `player.distance < 10`:
- cooldown alert 60s
- emit_global_signal "intruder_alert"
- say "Alert! Intruder spotted!"
</syntaxhighlight>

=== Conditional Greeter ===

<syntaxhighlight lang="yaml">
tree:
sequence:
- if `memory.has('greeted')`:
- say "Welcome back!"
else:
- sequence:
- say "Nice to meet you!"
- set greeted true
- cooldown greet 10s
- wait 2s
- say "Have a nice day!"
</syntaxhighlight>

=== Resource Gathering ===

<syntaxhighlight lang="yaml">
tree:
sequence:
- set gathered 0
- loop `memory.get('gathered', 0) < 5`:
- wander radius=20 pathfind=true
- wait 5s
- break_block `npc.location.x` `npc.location.y - 1` `npc.location.z`
- set gathered `memory.get('gathered', 0) + 1`
- say "Gathered {memory.get('gathered')} resources"
- say "Resource gathering complete!"
- teleport 0 64 0
</syntaxhighlight>

== Loading Behavior Trees ==

=== External File ===

You can load trees from external files in the <code>behaviors/</code> directory.

<syntaxhighlight lang="yaml">
traits:
- name: behavior
tree: patrol_behavior.yml
</syntaxhighlight>

The behaviors will be loaded from <code>plugins/Citizens/behaviors/patrol_behavior.yml</code>

=== Template System ===
Behavior trees can be included in templates:

<syntaxhighlight lang="yaml">
greeter:
traits:
- name: behavior
tree:
sequence:
- cooldown greet 10s
- say "Hello there, traveler!"
- wait 2s
</syntaxhighlight>

== API ==

=== Registering Custom Behaviors ===

Register custom behaviors with the BehaviorRegistry:

<syntaxhighlight lang="java">
registry.registerBehavior("my_behavior", (params, context) -> {
String arg = context.getArgOrParam(0, "param_name", params, "default");
ExpressionValue argHolder = registry.getExpressionRegistry().parseValue(arg);

return new InstantBehavior() {
@Override
public void reset() {
}

@Override
public BehaviorStatus run() {
NPC npc = context.getNPC();
// Your behavior logic here
return BehaviorStatus.SUCCESS;
}

@Override
public boolean shouldExecute() {
return true;
}
};
});
</syntaxhighlight>

=== Custom Expression Languages ===

Register custom expression engines with the ExpressionRegistry for domain-specific languages.

Behaviors - Revision history

Fullwall: /* Behaviors */

Fullwall: /* Tree Structure */

Fullwall: /* Tree Structure */

Fullwall: /* Tree Structure */