Skip to content

Commit 4c9c48d

Browse files
hugeblankhugeblank
committed
feat: script documentation
1 parent 755218a commit 4c9c48d

File tree

2 files changed

+116
-12
lines changed

2 files changed

+116
-12
lines changed

‎docs/reference/fundamentals.md‎

Lines changed: 13 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -147,15 +147,19 @@ boolean notLongString = foobar.invert(longString);
147147
:::
148148

149149
Types are converted as follows:
150-
| Lua Type | Java Type | Notes |
151-
| :--------: | :--------------------------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
152-
| `nil` | `null`, `void`, `Void` | Can only be used as `void` or `Void` when describing a method to create or override during class building. |
153-
| `number` | `byte`, `short`, `int`, `long`, `float`, `double`, `Byte`, `Short`, `Int`, `Long`, `Float`, `Double` | If a number greater than the max size of the Java type is provided, it will simply overflow and wrap around. (ex. if passing 256 where a byte is expected, the resulting byte will be 0) |
154-
| `boolean` | `boolean`, `Boolean` | |
155-
| `string` | `String` | |
156-
| `function` | * | When going from Lua to Java, converted to a functional interface (java interface with only one method), where applicable. see [Callback Methods](#callback-methods) |
157-
| `table` | `List`, `Set`, `Map` | When going from Java to Lua, converted only if the java method's return value is annotated with `@CoerceToNative`. When going from Lua to Java, converted unconditionally. |
158-
| `userdata` | *, `Class`, `EClass` | Java classes and objects are userdata and can be used where needed. Additionally, where a `Class` or `EClass` are expected, a userdata passed directly from `require` can be used. |
150+
| Lua Type | Java Type | Notes |
151+
| :--------: | :--------------------------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
152+
| `nil` | `null`, `void`, `Void` | Can only be used as `void` or `Void` when describing a method to create or override during class building. |
153+
| `number` | `byte`, `short`, `int`, `long`, `float`, `double`, `Byte`, `Short`, `Int`, `Long`, `Float`, `Double` | If a number greater than the max size of the Java type is provided, it overflows, wrapping around. (ex. if passing 256 where a byte is expected, the resulting byte will be 0) |
154+
| `boolean` | `boolean`, `Boolean` | |
155+
| `string` | `String` | |
156+
| `function` | *instance* | When going from Lua to Java, converted to an instance of a functional interface (java interface with only one method), where applicable. see [Callback Methods](#callback-methods) |
157+
| `table` | `List`, `Set`, `Map` | When going from Java to Lua, converted only if the java method's return value is annotated with `@CoerceToNative`. When going from Lua to Java, converted unconditionally. |
158+
| `userdata` | *instance*, `Class`, `EClass` | Java classes and objects are wrapped as userdata. Additionally, where a `Class` or `EClass` are expected, a userdata passed directly from `require` can be used. |
159+
160+
::: info
161+
In these docs, a userdata that wraps a class is represented as `userdata [class]`, while a userdata that wraps an object is represented as `userdata [instance]`. On a `userdata [class]` static methods and fields are accessible, while on a `userdata [instance]` instance methods and fields are accessible.
162+
:::
159163

160164
## Throwing exceptions
161165

‎docs/reference/scripts.md‎

Lines changed: 103 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,105 @@
1+
---
2+
outline: [2, 3]
3+
---
4+
15
# Scripts
26

3-
::: warning
4-
This page is under construction
5-
:::
7+
Scripts are a collection of one or more Lua files and a manifest JSON file, stored in a directory, a zip archive, or within a java mod.
8+
9+
10+
## Manifest
11+
12+
The manifest file describes information relevant to the execution of the script, and metadata that might be useful for other scripts.
13+
14+
The following values are required:
15+
- `id`: The script ID. Must match the regex pattern `[0-9a-z_]+` (lowercase alphanumeric & underscore.)
16+
- `version`: A version string. Does not have to be "[semver](https://semver.org/)", but consider making it make sense.
17+
- `name`: A proper, descriptive name of the script. May be capitalized.
18+
- `entrypoints`: The entrypoints from which this script launches from. See below.
19+
20+
### Entrypoints
21+
22+
Scripts are provided 3 entrypoints to launch from: mixin, static, and dynamic. Scripts **MUST** provide a static or dynamic entrypoint in order to be valid.
23+
24+
#### `mixin`
25+
26+
The mixin entrypoint is where mixin classes and interfaces are built and registered. This entrypoint is executed during the `preLaunch` phase, and should avoid doing anything other than mixin building.
27+
28+
For more information see [Mixin Library](/reference/mixin-lib).
29+
30+
#### `static`
31+
32+
The static entrypoint is where code that is unable to be reloaded should reside. For instance, anything that touches one of the games many registries found in the `BuiltinRegistries` class is unlikely to be able to be reloaded.
33+
34+
The first value returned by this entrypoint becomes the script's module. This module is provided to other scripts that `require()` this script's ID.
35+
36+
#### `dynamic`
37+
38+
The dynamic entrypoint is where code that *can* be reloaded should reside. This includes [mixin method hooks](/reference/mixin-lib#method-hook), and event handlers.
39+
40+
::: info
41+
Depending on where the mixin is, the reloadability might not be useful. For example if the mixin only executes once on launch then the reloaded hook will not be called.
42+
:::
43+
44+
### Example
45+
46+
```JSON5 [manifest.json]
47+
{
48+
"id": "example",
49+
"version": "1.0.0",
50+
"name": "Example Script",
51+
"entrypoints": {
52+
"mixin": "mixin.lua",
53+
"static": "main.lua",
54+
"dynamic": "dynamic.lua"
55+
}
56+
}
57+
```
58+
59+
## Functions
60+
61+
The `script` global is a `userdata [instance]` that represents the currently executing script. The following functions are provided.
62+
63+
### `script:getId()`
64+
65+
Gets the ID provided by the script manifest.
66+
67+
#### Returns
68+
69+
- `string`: The script ID.
70+
71+
### `script:getModule()`
72+
73+
Gets the module provided by the `static` entrypoint.
74+
75+
#### Returns
76+
77+
- `string`: The script module.
78+
79+
### `script:getName()`
80+
81+
Gets the name provided by the script manifest.
82+
83+
#### Returns
84+
85+
- `string`: The script name.
86+
87+
### `script:getVersion()`
88+
89+
Gets the version provided by the script manifest.
90+
91+
#### Returns
92+
93+
- `string`: The script version.
94+
95+
### `script:registerResource(resource)`
96+
97+
Register a temporary resource to this script that will close when the script unloads.
98+
99+
#### Parameters
100+
101+
1. `resource` - `userdata [instance]`: An instance of type [`ScriptResource`](https://github.com/moongardenmods/allium/blob/main/allium/src/main/java/dev/hugeblank/allium/api/ScriptResource.java).
102+
103+
#### Returns
104+
105+
- `userdata [instance]`: A wrapped instance of the `resource` that clears the dangling resource from within the script when `close()` is called.

0 commit comments

Comments
 (0)