You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Add new Create Block Edits reference and update documentation across the site. Improve Getting Started with recommended setup and examples, add Goggle API and Create Block Edits entries to the index, and refine wording and examples in Super Behaviours and RenderedBehaviourExtension (clarify lifecycle, Flywheel visual setup, examples, and helper usage). Minor formatting and API clarity improvements throughout docs/Super Behaviours/* and docs/Getting Started.md.
`CreateBlockEdits` lets a mod adjust Create's own block registrations while `AllBlocks` is still being built. That makes it possible to soft-mod existing Create blocks, add extra builder transforms, or swap the generated `BlockItem` class without replacing the block itself.
4
+
5
+
## Registering edits
6
+
7
+
Declare a public static no-arg method, annotate it with `@CreateBlockEdits.Registrator`, and register edits inside it:
The string id is the original Create registration name, such as `belt` or `fluid_pipe`.
28
+
29
+
## API overview
30
+
31
+
|API|Description|
32
+
|---|---|
33
+
| `@CreateBlockEdits.Registrator` |Marks a `publicstaticvoid register()` method for automatic discovery during Create block bootstrap. |
34
+
| `CreateBlockEdits.forBlock(id, edit)` |Applies an extra transform to Create's original `BlockBuilder` for that id. |
35
+
| `CreateBlockEdits.forBlockItem(id, factory)` | Replaces the generated `BlockItem` factory for that id. |
36
+
37
+
## `@CreateBlockEdits.Registrator`
38
+
39
+
Registrator methods are discovered automatically from NeoForge scan data when Create's `AllBlocks` classstarts bootstrapping. No manual bootstrap call is required from mod setup.
40
+
41
+
The method signature is strict:
42
+
43
+
```java
44
+
@CreateBlockEdits.Registrator
45
+
publicstatic void register() {
46
+
// edits go here
47
+
}
48
+
```
49
+
50
+
Anythingelse, such as private methods, instance methods, parameters, or a non-`void` return type, throws an `IllegalStateException` during discovery.
51
+
52
+
## `forBlock(...)`
53
+
54
+
`forBlock(...)` exposes the original `BlockBuilder<?, CreateRegistrate>` so extra registration transforms can be layered onto Create's own block definition.
55
+
56
+
```java
57
+
CreateBlockEdits.forBlock("belt", builder ->
58
+
builder.properties(p -> p.noOcclusion())
59
+
);
60
+
```
61
+
62
+
Multiple edits for the same id are merged and run in registration order. This makes it practical for separate compat modules to contribute independent builder changes to the same Create block.
63
+
64
+
## `forBlockItem(...)`
65
+
66
+
`forBlockItem(...)` replaces the generated item factory for a Create block, generally for when blocks dont have an explicit item themselves.
Only one item override may exist for a given block id. Registering a second one for the same id throws an `IllegalStateException`. This makes block items mutually exclusive to use with multiple edits on the same block, so should only be used when item classes dont exist and cannot have mixins.
73
+
74
+
## Timing rules
75
+
76
+
> `forBlock(...)` and `forBlockItem(...)` only work while a `@CreateBlockEdits.Registrator` method is running. Calling them later throws an `IllegalStateException` because the Create registration window is already closed.
77
+
78
+
Azimuth opens that window automatically from a mixin on Create's `AllBlocks` bootstrap, then applies the collected block edits and item overrides as the original Create registrations are created.
79
+
80
+
## Case study use cases
81
+
82
+
`Create:Bits'n'Bobs` uses `CreateBlockEdits` in two practical ways:
83
+
84
+
- `forBlock("belt", ...)` adds emissive rendering to Create's belt block when the custom `glowing` property is enabled, which then gets external handling to add the interaction check.
85
+
- `forBlockItem("fluid_pipe", ...)` swaps the normal pipe item for `DyeablePipeBlockItem`, which carries the extra placement behavior used by the dyeable pipe system, since pipes dont have their own item class to mixin into.
86
+
87
+
That is the intended pattern when the base Create block should stay intact but its registration-time properties or generated item class need to change.
Copy file name to clipboardExpand all lines: docs/Getting Started.md
+36-6Lines changed: 36 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,18 +1,18 @@
1
-
# Getting Started
1
+
# Getting Started
2
2
3
-
Azimuth is a Create addon library focused on making it easier to extend the functionality of Create.
3
+
Azimuth is a Create addon library focused on making it easier to extend Create without forking large chunks of block entity or registration code.
4
4
5
5
## Adding Azimuth to your project
6
6
7
-
Add the following to your`build.gradle` dependencies block, replacing `<version>` with the version you want to target, [the latest production-ready version is available here](https://modrinth.com/project/azimuth-api/settings/versions):
7
+
Add the following to the`build.gradle` dependencies block, replacing `<version>` with the version to target. [The latest production-ready version is available here](https://modrinth.com/project/azimuth-api/settings/versions):
You may also need to declare Azimuth as a required dependency in your`neoforge.mods.toml`:
15
+
It may also be necessary to declare Azimuth as a required dependency in `neoforge.mods.toml`:
16
16
17
17
```toml
18
18
[[dependencies.yourmodid]]
@@ -23,22 +23,52 @@ You may also need to declare Azimuth as a required dependency in your `neoforge.
23
23
side = "BOTH"
24
24
```
25
25
26
-
Azimuth doesn't require any explicit initialisation on your part just depend on it and start using the APIs.
26
+
Most Azimuth APIs are ready as soon as the dependency is present. The one setup pattern worth knowing is behaviour and visual registration.
27
+
28
+
## Recommended common setup
29
+
30
+
If a mod registers type-specific behaviour applicators or Flywheel visual interest predicates, resolve them during common setup once the registries exist:
`BehaviourApplicators.resolveRegisteredTypes()` is relevant for `registerForType(...)` suppliers. `VisualWrapperInterest.resolve()` is only relevant for `RenderedBehaviourExtension` visuals created through `getVisualFactory()`. Plain BER rendering does not need it.
27
45
28
46
## What's available
29
47
30
48
### Super Block Entity Behaviours
31
49
32
-
An expanded version of Create's `BlockEntityBehaviour`that can do significantly more, in effort to replicate features that would typically take new block entity types. All of which is composable on a single `SmartBlockEntity`. You can also *inject* behaviours onto block entities you don't own, without touching their source, making simple soft-compatability easy.
50
+
An expanded version of Create's `BlockEntityBehaviour`with full tick lifecycle support, extra interaction hooks, typed lookup helpers, and extension interfaces for rendering, kinetics, and schematic requirements. Behaviours can also be injected onto block entities that are not owned by the mod.
A registration-time API for soft-modding Create's own blocks. Use it to apply extra `BlockBuilder` transforms or replace the generated `BlockItem` for an existing Create block id.
57
+
58
+
[Create Block Edits](./Create%20Block%20Edits.md)
59
+
36
60
### Advancements
37
61
38
62
A thin wrapper around Create's internal advancement machinery. Define advancements in the same style Create uses, generate the required data, and award them from anywhere including from a block entity via `AzimuthAdvancementBehaviour`.
39
63
40
64
[Advancements](./Advancements/Advancements.md)
41
65
66
+
### Goggle API
67
+
68
+
A declarative builder for Create goggle tooltips, including labels, statistics, preset styles, and language key collection for datagen.
69
+
70
+
[Goggle API](./Goggle%20API/Goggle%20API.md)
71
+
42
72
### Outlines
43
73
44
74
Extra outline types built on top of Catnip's outliner. Particularly handy for ponders.
`RenderedBehaviourExtension` lets a behaviour contribute rendering output alongside the block entity it's attached to. There are two rendering paths available: a standard Block Entity Renderer (BER) that works unconditionally, and an optional Flywheel visual for hardware-accelerated rendering. You can use either path or both together.
3
+
`RenderedBehaviourExtension` lets a behaviour contribute rendering output alongside the block entity it is attached to. Two rendering paths are available: a standard Block Entity Renderer (BER) that always works, and an optional Flywheel visual for hardware-accelerated rendering.
4
4
5
5
For an overview of all extensions, see [Super Block Entity Behaviours](../Super%20Behaviours.md#extensions).
6
6
7
7
## Implementing
8
8
9
+
To use a renderer, it is suggested you create a public static final supplier instance, which functions as a singleton for the renderer factory. This is not strictly required, but it is more efficient to reuse the same supplier instance across all behaviour instances than to create a new one for each:
@@ -23,97 +26,102 @@ public class MyRenderedBehaviour extends SuperBlockEntityBehaviour
23
26
24
27
@Override
25
28
publicBehaviourRenderSuppliergetRenderer() {
26
-
return() -> () ->newMyBehaviourRenderer();
29
+
returnRENDERER;
27
30
}
28
31
}
29
32
```
30
33
31
-
32
34
## Block Entity Renderer (BER)
33
35
34
36
### `getRenderer()`
35
37
36
-
**Required.** Returns a `BehaviourRenderSupplier` a double-supplier that produces a new `BlockEntityBehaviourRenderer` instance. The renderer's `renderSafe` method is called each frame while the block entity is in view.
38
+
Required. Returns a `BehaviourRenderSupplier`, which produces a new `BlockEntityBehaviourRenderer` instance when Azimuth needs one.
The type parameter `T`determines what the `blockEntity` argument is cast to. If the cast fails at runtime, an informative `ClassCastException` is thrown.
51
+
The type parameter `T`controls the type of the `blockEntity` argument. If the cast fails at runtime, Azimuth throws an informative `ClassCastException`.
50
52
51
53
### `rendersWhenVisualizationAvailable()`
52
54
53
-
Controls whether the BER runs even when a Flywheel visual is also active for this block entity. Defaults to `true`. Override to return `false`if your BER and Flywheel visual would produce duplicate output and you only want the visual to run.
55
+
Controls whether the BER still runs when a Flywheel visual is active for the same block entity. The default is `true`. Return `false`when the visual fully replaces the BER output.
54
56
55
57
### `getRenderBoundingBox()`
56
58
57
-
Optional. Return an `AABB` to expand the culling bounding box for this block entity. Returning `null` (default) leaves it untouched.
58
-
59
-
> If you add a `RenderedBehaviourExtension`*after* the block entity has already been rendered (i.e. deferred), call `((CachedRenderBBBlockEntity) blockEntity).invalidateRenderBoundingBox()` to force a client-side refresh.
59
+
Optional. Return an `AABB` to expand the culling bounds for the owning block entity. Returning `null` leaves the bounds unchanged.
60
60
61
+
> If a `RenderedBehaviourExtension` is attached after the block entity has already been rendered, call `((CachedRenderBBBlockEntity) blockEntity).invalidateRenderBoundingBox()` to force a client-side refresh.
61
62
62
63
## Flywheel Visual Interest
63
64
64
-
Flywheel visuals from `RenderedBehaviourExtension` are injected via a wrapping visualizer. To keep the overhead minimal, you must explicitly declare which block entity types need the wrapper types that aren't registered are left untouched.
65
-
66
-
Call this once during client setup for any type that will host a behaviour using `getVisualFactory()`:
65
+
Flywheel visuals are injected through a wrapping visualizer. Register interest only for the block entity types that might actually create a behaviour visual:
67
66
68
67
```java
69
-
VisualWrapperInterest.registerInterest(type ->
70
-
type ==MyBlockEntityType.MY_TYPE.get()
71
-
);
72
-
```
73
-
74
-
This is only required for the Flywheel visual path. Plain BER rendering works without it.
0 commit comments