Skip to content

Commit d247deb

Browse files
committed
add argument conversion notes
1 parent a12b3e6 commit d247deb

File tree

1 file changed

+56
-1
lines changed

1 file changed

+56
-1
lines changed

docs/src/controlling-script-bindings.md

Lines changed: 56 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ In this book we reffer to anything accessible by a script, which allows it to co
44

55
The "binding" here being used as in: binding `script` code to `rust` code.
66

7-
## Function Registry
7+
## Dynamic Functions
88

99
Everything callable by scripts must first be registered in the dynamic function registry. Notably we do not make use of the normal bevy function registry to improve performance and usability. This means you cannot call just any function.
1010

@@ -22,5 +22,60 @@ These wrappers enable us to safely interact with bevy, and claim any necessary m
2222

2323
The `GetInnerTypeDependencies`, trait is simply a local trait alias for `GetTypeRegistration` with less strict type requirements. It allows us to register all the types necessary for the function calls, so that you don't have to register anything manually. If your type implements `GetTypeRegistration` you should not face any issues on this front.
2424

25+
## Registering Script Functions
2526

27+
Registering functions can be done via the `NamespaceBuilder` like below:
28+
29+
```rust,ignore
30+
NamespaceBuilder::<ReflectReference>::new(&mut world)
31+
.register(
32+
"hello_world",
33+
|s: String| {
34+
println!(s)
35+
},
36+
);
37+
```
38+
39+
This will allow you to call this function within lua like so:
40+
41+
```lua
42+
hello_world("hi from lua!")
43+
```
44+
45+
## Context Arguments
46+
47+
Each script function call always receives 2 context arguments, namely:
48+
- `CallerContext`
49+
- `WorldCallbackAccess`
50+
51+
The first one is configured by the caller, and contains requests from the caller to your function, such as "I am calling you from a 1-indexed array system, please convert the index first", This argument is only relevant if you're targeting multiple languages.
52+
53+
The second argument gives you access to the world from your function.
54+
55+
You can opt-in to receive these arguments by adding them to your closure arguments in the above order (either both or just one)
56+
57+
## Generic Arguments
58+
59+
Sometimes you might want to be generic over the type of argument you're accepting, you can do so by accepting `ScriptValue` arguments like so:
60+
61+
```rust,ignore
62+
NamespaceBuilder::<ReflectReference>::new(&mut world)
63+
.register(
64+
"is_integer",
65+
|s: ScriptValue| {
66+
match s {
67+
ScriptValue::Integer(i) => true,
68+
_ => false
69+
}
70+
},
71+
);
72+
```
73+
74+
You can treat return values similarly.
75+
76+
## Fallible functions
77+
78+
Your script functions can return errors either by:
79+
- Returning `Result<T: IntoScript, InteropError>`
80+
- Returning `ScriptValue` and manually creating the `ScriptValue::Error(into_interop_erorr.into())` variant.
2681

0 commit comments

Comments
 (0)