Skip to content

Commit 53edefd

Browse files
rlntrlnt
committed
kjs-ori: add particle state event docs
1 parent 94b4a6d commit 53edefd

5 files changed

Lines changed: 254 additions & 0 deletions

File tree

‎wikis/kubejs-oritech/.vitepress/config.mts‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,14 @@ export default defineConfig({
4848
{ text: "Deep Drill Registration", link: "event/deepdrill_registration" },
4949
{ text: "Soul Collection", link: "event/soulcollection" },
5050
{ text: "Tags", link: "event/tags" },
51+
{
52+
text: "Particle Accelerator",
53+
items: [
54+
{ text: "Injected", link: "event/particle/injected" },
55+
{ text: "Collided", link: "event/particle/collided" },
56+
{ text: "Exited", link: "event/particle/exited" },
57+
],
58+
},
5159
],
5260
},
5361
],

‎wikis/kubejs-oritech/docs/event/particle/collided.md‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# Particle Collided Event
2+
3+
This event allows you to invoke logic when a particle collides in the
4+
[Particle Accelerator](../../recipe/machine/particle_accelerator.md). Colliding refers to controlled particle movement that results in a successful collision. For particles that exit the accelerator without colliding, refer to the
5+
[particle exited event](exited.md).
6+
7+
> [!WARNING] NOTE
8+
> This event only exists since mod version 1.21.1-0.3.0, release date: 2026-02-06.
9+
10+
**It is a server event and reloadable!**
11+
Keep in mind that server events have to be located inside the `kubejs/server_scripts` folder.
12+
13+
## Overview
14+
15+
This event is fired when a particle collision happens in the Particle Accelerator, but before checking if the collision matches a
16+
valid recipe. By cancelling the event, the collision will still happen, but not result in any item output, which is the samee thing
17+
that happens when no valid recipe is found.
18+
19+
- access in a server script via: `OritechEvents.particleCollided`
20+
- properties
21+
- `level`
22+
- type: `ServerLevel`
23+
- description: the level where the particle collision is happening
24+
- `pos`
25+
- type: `BlockPos`
26+
- description: the position of the accelerator controller
27+
- `controller`
28+
- type: `AcceleratorControllerBlockEntity`
29+
- description: the `BlockEntity` of the accelerator controller block
30+
- `collisionPos`
31+
- type: `BlockPos`
32+
- description: the position in the world where the particle collision is happening
33+
- `itemA`
34+
- type: `ItemStack`
35+
- description: the first item that is being collided
36+
- `itemB`
37+
- type: `ItemStack`
38+
- description: the second item that is being collided
39+
- `speed`
40+
- type: `float`
41+
- description: the speed of the particle collision (added speeds of both particles)
42+
- `recipeId`
43+
- type: `ResourceLocation` (nullable)
44+
- description: the recipe id of the matched recipe; null if no valid recipe was found for this collision
45+
- `recipe`
46+
- type: `OritechRecipe` (nullable)
47+
- description: the matched recipe; null if no valid recipe was found for this collision
48+
- functions
49+
- `cancel()`
50+
- description: cancels the particle collision; collision still happens but no item output will be produced, even if a recipe matches
51+
52+
## Event Listener
53+
54+
To access the event, the first thing you need to do is to open an event listener for the `particleCollided` event in a server script.
55+
56+
```js
57+
OritechEvents.particleCollided(event => {
58+
// ...
59+
})
60+
```
61+
62+
After that, you can apply logic to modify the particle collision behavior.
63+
64+
## Example
65+
66+
```js
67+
OritechEvents.particleCollided(event => {
68+
// obtaining all properties of the event by destructuring
69+
let { level, pos, controller, collisionPos, itemA, itemB, speed, recipeId, recipe } = event
70+
71+
// if the recipe id is null, there was no recipe meaning unmatched items have collided
72+
if (recipeId == null) return
73+
74+
// disable particle collision for a specific recipe
75+
if (recipeId === "mymodpack:particle_accelerator/recipe1") {
76+
event.cancel()
77+
}
78+
})
79+
```

‎wikis/kubejs-oritech/docs/event/particle/exited.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# Particle Exited Event
2+
3+
This event allows you to invoke logic when a particle exits the [Particle Accelerator](../../recipe/machine/particle_accelerator.md).
4+
Exiting refers to uncontrolled particle movement leaving the accelerator. For successful particle exits, refer to the
5+
[particle collided event](collided.md).
6+
7+
> [!WARNING] NOTE
8+
> This event only exists since mod version 1.21.1-0.3.0, release date: 2026-02-06.
9+
10+
**It is a server event and reloadable!**
11+
Keep in mind that server events have to be located inside the `kubejs/server_scripts` folder.
12+
13+
## Overview
14+
15+
This event is fired when an a particle leaves the Particle Accelerator without colliding with another particle. This can happen if
16+
the particle becomes too fast and can't be contained by the accelerator, for example.
17+
18+
- access in a server script via: `OritechEvents.particleExited`
19+
- properties
20+
- `level`
21+
- type: `ServerLevel`
22+
- description: the level where the particle exited
23+
- `pos`
24+
- type: `BlockPos`
25+
- description: the position of the accelerator controller
26+
- `controller`
27+
- type: `AcceleratorControllerBlockEntity`
28+
- description: the `BlockEntity` of the accelerator controller block
29+
- `gatePos`
30+
- type: `BlockPos`
31+
- description: the position of the last gate the particle passed through before exiting
32+
- `fromVec`
33+
- type: `Vec3`
34+
- description: the vector from which the particle came from
35+
- `toVec`
36+
- type: `Vec3`
37+
- description: the vector to which the particle is heading
38+
- `directionVec`
39+
- type: `Vec3`
40+
- description: the normalized vector that represents the direction of the particle movement
41+
- `reason`
42+
- type: `ParticleEvent`
43+
- description: the reason why the particle exited
44+
- possible values:
45+
- `IDLE` - nothing was insert yet; should not be possible in a valid scenario
46+
- `ERROR` - no ring was found; should not be possible in a valid scenario
47+
- `ACCELERATING` - particle is in collider; should not be possible in a valid scenario
48+
- `COLLIDED` - particle collided with another particle; should not be possible in a valid scenario
49+
- `EXITED_FAST` - particle was too fast to take curve
50+
- `EXITED_NO_GATE` - no gate found in range; particle was to slow to bridge the gap between gates
51+
52+
## Event Listener
53+
54+
To access the event, the first thing you need to do is to open an event listener for the `particleExited` event in a server script.
55+
56+
```js
57+
OritechEvents.particleExited(event => {
58+
// ...
59+
})
60+
```
61+
62+
After that, you can apply logic when the particle exits the accelerator.
63+
64+
## Example
65+
66+
```js
67+
OritechEvents.particleExited(event => {
68+
// obtaining all properties of the event by destructuring
69+
let { level, pos, controller, gatePos, fromVec, toVec, directionVec, reason } = event
70+
71+
// make it rain if a particle exited because it was too fast
72+
// the reason can be checked against a simple string, case insensitive
73+
if (reason === "exited_fast") {
74+
level.levelData.setRaining(true)
75+
}
76+
})
77+
```

‎wikis/kubejs-oritech/docs/event/particle/injected.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
# Particle Injected Event
2+
3+
This event allows you to invoke logic when a particle is injected into the
4+
[Particle Accelerator](../../recipe/machine/particle_accelerator.md). It can also be used to cancel the injection completely.
5+
6+
> [!WARNING] NOTE
7+
> This event only exists since mod version 1.21.1-0.3.0, release date: 2026-02-06.
8+
9+
**It is a server event and reloadable!**
10+
Keep in mind that server events have to be located inside the `kubejs/server_scripts` folder.
11+
12+
## Overview
13+
14+
This event is fired when an item is inserted into a Particle Accelerator Controller and the controller tries to push the item into the
15+
accelerator in the world. By cancelling the event, the item will not be injected into the accelerator and never leave the input slot.
16+
17+
Additionally, you can disable special interactions such as the creation of an End or a Nether portal by particle collision. This is
18+
useful if you want to avoid that players access these dimensions or if you want to make your own recipes with the same items that are
19+
normally reserved for portal creation.
20+
21+
- access in a server script via: `OritechEvents.particleInjected`
22+
- properties
23+
- `level`
24+
- type: `ServerLevel`
25+
- description: the level where the particle injection is happening
26+
- `pos`
27+
- type: `BlockPos`
28+
- description: the position of the accelerator controller
29+
- `controller`
30+
- type: `AcceleratorControllerBlockEntity`
31+
- description: the `BlockEntity` of the accelerator controller block
32+
- `startPos`
33+
- type: `BlockPos`
34+
- description: the position at which the particle is being injected
35+
- `gatePos`
36+
- type: `BlockPos`
37+
- description: the position of the first gate the particle is heading towards after successful injection
38+
- `particle`
39+
- type: `Particle`
40+
- description: the particle that is being injected
41+
- `item`
42+
- type: `ItemStack`
43+
- description: the item that is being injected as a particle
44+
- functions
45+
- `cancel()`
46+
- description: cancels the particle injection
47+
- `disableNetherPortal()`
48+
- description: disables the special interaction that creates a nether portal
49+
- `disableEndPortal()`
50+
- description: disables the special interaction that creates an end portal
51+
52+
## Event Listener
53+
54+
To access the event, the first thing you need to do is to open an event listener for the `particleInjected` event in a server script.
55+
56+
```js
57+
OritechEvents.particleInjected(event => {
58+
// ...
59+
})
60+
```
61+
62+
After that, you can apply logic to modify the particle injection behavior.
63+
64+
## Example
65+
66+
```js
67+
OritechEvents.particleInjected(event => {
68+
// disable the special interactions that create portals
69+
event.disableNetherPortal()
70+
event.disableEndPortal()
71+
72+
// obtaining all properties of the event by destructuring
73+
let { level, pos, controller, startPos, gatePos, particle, item } = event
74+
75+
// disable particle injection during the day
76+
let dayTime = level.levelData.dayTime
77+
if (dayTime >= 0 && dayTime <= 12000) {
78+
event.cancel()
79+
}
80+
})
81+
```

‎wikis/kubejs-oritech/docs/recipe/machine/particle_accelerator.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,15 @@ The Particle Accelerator is a machine that can drastically speed up matter to co
2525
- default: `60`
2626
- description: specifies the required energy in Joules for the collision; higher values require higher speed
2727

28+
## Events
29+
30+
If you want to adjust the behavior of the particle accelerator beyond just adding or removing recipes, there are three events that allow
31+
you to do so.
32+
33+
- [particle injected event](../../event/particle/injected.md)
34+
- [particle collided event](../../event/particle/collided.md)
35+
- [particle exited event](../../event/particle/exited.md)
36+
2837
## Examples
2938

3039
```js

0 commit comments

Comments
 (0)