Started actual docs

Author: cakeGit

.vitepress/config.mjs

@@ -120,7 +120,7 @@ function buildSidebar() {
   }
 
   // Prepend a home link
-  sidebar.unshift({ text: 'home', link: '/azimuth' });
+  sidebar.unshift({ text: 'home', link: '/' });
   return sidebar;
 }
 
@@ -132,17 +132,17 @@ function basenameWithoutExt(fullPath) {
 const sidebar = buildSidebar();
 
 export default defineConfig({
-  title: "Azimuth Docs",
+  title: "Azimuth",
   description: "Documentation of the Azimuth library",
   themeConfig: {
     nav: [
-      { text: 'home', link: '/azimuth' },
+      { text: 'home', link: '/' },
     ],
 
     sidebar: sidebar,
 
     socialLinks: [
-      { icon: 'github', link: 'https://github.com/vuejs/vitepress' }
+      { icon: 'github', link: 'https://github.com/Industrialists-Of-Create/AzimuthDocs' }
     ]
   },
   srcDir: 'docs',

docs/Advancements/Advancements.md

@@ -0,0 +1,198 @@
+# Advancements
+
+Azimuth provides a Create-compatible advancement system that closely mirrors how Create handles its own advancements internally. The goal is to let addon authors define and award advancements without having to wire up all the boilerplate themselves and, importantly, without needing to know Create's internals.
+
+There are three main classes involved:
+
+| Class | Role |
+| --- | --- |
+| `AzimuthAdvancementProvider` | Central registry for a mod's advancements. Handles datagen and lang generation. |
+| `AzimuthAdvancement` | A single advancement definition icon, title, description, trigger, parent. |
+| `AzimuthAdvancementBehaviour` | A `BlockEntityBehaviour` for tracking and awarding advancements from block entities. |
+
+
+## Setting up `AzimuthAdvancementProvider`
+
+Create one static `AzimuthAdvancementProvider` for your mod and define all your advancements on it:
+
+```java
+public class MyAdvancements {
+
+    public static final AzimuthAdvancementProvider PROVIDER =
+        new AzimuthAdvancementProvider(MyMod.MOD_ID, "My Mod Advancements");
+
+    public static final AzimuthAdvancement ROOT = PROVIDER.create("root", b -> b
+        .icon(MyItems.MY_ITEM)
+        .title("My Mod")
+        .description("Get started with My Mod.")
+        .after(() -> AllAdvancements.ROOT) // display inside the Create tab omit to create a new advancement tab
+        .awardedForFree()                  // immediately award when the player first joins
+        .special(AzimuthAdvancement.TaskType.SILENT)
+    );
+
+    public static final AzimuthAdvancement FIRST_CRAFT = PROVIDER.create("first_craft", b -> b
+        .icon(MyItems.MY_ITEM)
+        .title("First Steps")
+        .description("Craft your first widget.")
+        .after(ROOT)
+        .whenItemCollected(MyItems.MY_ITEM)
+    );
+}
+```
+
+Then wire it into datagen. Call `register()` during common mod init, then hook `provideLang` and `dataProvider` into your datagen event:
+
+```java
+// In your mod class or init method
+MyAdvancements.PROVIDER.register();
+
+// In your GatherDataEvent handler
+public static void gatherData(final GatherDataEvent event) {
+    final PackOutput output = event.getGenerator().getPackOutput();
+    final CompletableFuture<HolderLookup.Provider> lookupProvider = event.getLookupProvider();
+
+    YourMod.REGISTRATE.addDataGenerator(ProviderType.LANG, provider -> {
+        final BiConsumer<String, String> langConsumer = provider::add;
+        MyAdvancements.PROVIDER.provideLang(langConsumer);
+    });
+
+    event.getGenerator().addProvider(
+        event.includeServer(),
+        MyAdvancements.PROVIDER.dataProvider(output, lookupProvider)
+    );
+}
+```
+
+
+## Advancement builder options
+
+The builder passed to `PROVIDER.create(...)` supports the following:
+
+### Icon
+
+```java
+.icon(MyItems.MY_ITEM)           // ItemProviderEntry<?, ?>
+.icon(Items.IRON_INGOT)          // ItemLike
+.icon(new ItemStack(Items.BOOK)) // ItemStack, for NBT-specific icons
+```
+
+### Title and description
+
+```java
+.title("My Advancement Title")
+.description("A short description shown in the advancement screen.")
+```
+
+Lang keys are automatically generated as `advancement.<modid>.<id>` and `advancement.<modid>.<id>.desc`.
+
+### Parent
+
+Chain advancements by passing the parent definition:
+
+```java
+.after(ROOT)                                        // AzimuthAdvancement
+.after(AllAdvancements.ANDESITE_ALLOY)              // CreateAdvancement
+.after(ResourceLocation.fromNamespaceAndPath(...))  // raw ResourceLocation
+```
+
+Leave out `.after(...)` entirely for the root advancement of your tree (its background texture is expected at `textures/gui/advancements.png` in your mod namespace).
+
+### Task type
+
+```java
+.special(AzimuthAdvancement.TaskType.NORMAL)  // default
+```
+
+| Type | Toast | Announce | Hidden |
+| --- | --- | --- | --- |
+| `SILENT` | No | No | No |
+| `NORMAL` | Yes | No | No |
+| `NOISY` | Yes | Yes | No |
+| `EXPERT` | Yes | Yes | No |
+| `SECRET` | Yes | Yes | Yes |
+
+`SECRET` also appends a "Hidden Advancement" suffix to the description automatically.
+
+### Triggers
+
+If you want the advancement to be awarded by a game event (rather than manually), use one of the built-in trigger helpers:
+
+```java
+.whenBlockPlaced(MyBlocks.MY_BLOCK.get())       // placed a specific block
+.whenItemCollected(MyItems.MY_ITEM)             // item entered inventory
+.whenItemCollected(MyTags.Items.MY_TAG)         // tag variant
+.whenIconCollected()                            // shorthand for the icon item
+.awardedForFree()                               // always awarded (useful for roots)
+.externalTrigger(myCriterion)                   // raw Criterion<?> for anything else
+```
+
+If none of these are called, a built-in `SimpleCreateTrigger` is created automatically. You can then award the advancement manually (see below).
+
+
+## Awarding advancements manually
+
+If the advancement uses the built-in trigger (no `.whenX` call), award it directly:
+
+```java
+MyAdvancements.FIRST_CRAFT.awardTo(player);
+```
+
+You can also check whether a player already has it:
+
+```java
+if (!MyAdvancements.FIRST_CRAFT.isAlreadyAwardedTo(player)) {
+    // do something
+}
+```
+
+`awardTo` will throw `UnsupportedOperationException` if the advancement uses an external trigger.
+
+
+## `AzimuthAdvancementBehaviour`
+
+If you want a block entity to track a player and award advancements when they interact with it, add `AzimuthAdvancementBehaviour` to its behaviour list:
+
+```java
+@Override
+public void addBehaviours(List<BlockEntityBehaviour> behaviours) {
+    super.addBehaviours(behaviours);
+    AzimuthAdvancementBehaviour.create(behaviours, this,
+        MyAdvancements.FIRST_CRAFT,
+        MyAdvancements.ANOTHER_ONE
+    );
+}
+```
+
+Using the static `create` method (rather than constructing directly) means that if multiple callers add the behaviour, they'll merge into a single instance rather than duplicate.
+
+### Tracking the player
+
+Call `setPlacedBy` from your block's `setPlacedBy` override to register the player who placed it:
+
+```java
+@Override
+public void setPlacedBy(Level level, BlockPos pos, BlockState state, LivingEntity placer, ItemStack stack) {
+    super.setPlacedBy(level, pos, state, placer, stack);
+    AzimuthAdvancementBehaviour.setPlacedBy(level, pos, placer);
+}
+```
+
+Fake players are ignored automatically.
+
+### Awarding from the behaviour
+
+```java
+// Award if the player is within maxDistance blocks
+behaviour.awardPlayerIfNear(MyAdvancements.FIRST_CRAFT, 8);
+
+// Award unconditionally
+behaviour.awardPlayer(MyAdvancements.FIRST_CRAFT);
+```
+
+Or use the static shorthand if you only have a position:
+
+```java
+AzimuthAdvancementBehaviour.tryAward(level, pos, MyAdvancements.FIRST_CRAFT);
+```
+
+Already-awarded advancements are pruned from the behaviour's tracked set automatically. Once all tracked advancements for a player have been awarded, the player reference is cleared.

docs/Getting Started.md

@@ -0,0 +1,46 @@
+# Getting Started
+
+Azimuth is a Create addon library focused on making it easier to extend the functionality of Create.
+
+## Adding Azimuth to your project
+
+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):
+
+```groovy
+dependencies {
+    implementation "com.cake.azimuth:azimuth:<version>"
+}
+```
+
+You may also need to declare Azimuth as a required dependency in your `neoforge.mods.toml`:
+
+```toml
+[[dependencies.yourmodid]]
+    modId = "azimuth"
+    type = "required"
+    versionRange = "[<version>,)"
+    ordering = "AFTER"
+    side = "BOTH"
+```
+
+Azimuth doesn't require any explicit initialisation on your part just depend on it and start using the APIs.
+
+## What's available
+
+### Super Block Entity Behaviours
+
+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.
+
+[Super Block Entity Behaviours](./Super Behaviours/Super Behaviours.md)
+
+### Advancements
+
+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`.
+
+[Advancements](./Advancements/Advancements.md)
+
+### Outlines
+
+Extra outline types built on top of Catnip's outliner. Particularly handy for ponders.
+
+[Outlines](./Outlines/Outlines.md)

docs/Outlines/Outlines.md

@@ -0,0 +1,42 @@
+# Outlines
+
+Azimuth adds extra outline types built on top of Catnip's `LineOutline`. These are particularly useful in ponders, where animated visual cues help guide the player's attention.
+
+## `ExpandingLineOutline`
+
+A `LineOutline` that animates from its midpoint outward, expanding to full length over a configurable number of ticks. The expansion uses an ease-out cubic curve, so it decelerates naturally as it reaches full size.
+
+```java
+ExpandingLineOutline outline = new ExpandingLineOutline();
+outline
+    .set(start, end)            // Vec3 start and end points
+    .setGrowingTicks(10)        // how many ticks the expansion takes
+    .setGrowingTicksElapsed(0); // tick counter increment each tick to drive the animation
+```
+
+Call `tickGrowingTicksElapsed()` each tick to advance the animation. Once elapsed reaches `growingTicks`, the outline stays at full size.
+
+
+## `ExpandingLineOutlineInstruction`
+
+A ready-to-use Ponder `TickingInstruction` that wraps `ExpandingLineOutline`. Just add it to your scene and it handles everything.
+
+```java
+scene.addInstruction(new ExpandingLineOutlineInstruction(
+    PonderPalette.WHITE,         // color palette
+    new Vec3(0.5, 1.0, 0.5),    // start point
+    new Vec3(2.5, 1.0, 0.5),    // end point
+    40,                          // total duration in ticks
+    10                           // growing ticks how long the expand animation takes
+));
+
+// Optionally specify line width (defaults to 1/16):
+scene.addInstruction(new ExpandingLineOutlineInstruction(
+    PonderPalette.WHITE,
+    new Vec3(0.5, 1.0, 0.5),
+    new Vec3(2.5, 1.0, 0.5),
+    40,
+    10,
+    1 / 8f                       // custom line width
+));
+```

docs/Super Behaviours/Extension Reference.md

@@ -0,0 +1,11 @@
+# Extension Reference
+
+Extensions are marker interfaces that opt a `SuperBlockEntityBehaviour` into additional systems. They're picked up lazily and cached per block entity, so behaviours that don't implement a given extension have zero impact on that system's cost.
+
+For more about `SuperBlockEntityBehaviour`s, see [Super Block Entity Behaviours](./Super Behaviours.md).
+
+| Extension | Description |
+| --- | --- |
+| [`KineticBehaviourExtension`](./Kinetic Extension.md) | Adds propagation positions and rotation transfer overrides for kinetic networks. |
+| [`RenderedBehaviourExtension`](./Rendered Extension.md) | Adds behaviour-level BER rendering, optional Flywheel visuals, and optional render bounds expansion. |
+| [`ItemRequirementBehaviourExtension`](./Item Requirement Extension.md) | Adds per-behaviour item requirements to schematic requirement flows. |

docs/Super Behaviours/Item Requirement Extension.md

@@ -0,0 +1,37 @@
+# ItemRequirementBehaviourExtension
+
+`ItemRequirementBehaviourExtension` lets a behaviour contribute item requirements to Create's schematic placement flow. Implement this if your behaviour places or represents items that should be listed when a player is deploying a schematic containing this block.
+
+For an overview of all extensions, see [Super Block Entity Behaviours](./Super Behaviours.md#extensions).
+
+## Implementing
+
+```java
+public class MyBehaviour extends SuperBlockEntityBehaviour
+        implements ItemRequirementBehaviourExtension {
+
+    public static final BehaviourType<MyBehaviour> TYPE = new BehaviourType<>();
+
+    public MyBehaviour(SmartBlockEntity be) {
+        super(be);
+    }
+
+    @Override
+    public BehaviourType<?> getType() {
+        return TYPE;
+    }
+
+    @Override
+    public ItemRequirement getRequiredItems(BlockState state) {
+        return new ItemRequirement(
+            ItemRequirement.ItemUseType.CONSUME,
+            List.of(new ItemRequirement.StackRequirement(
+                new ItemStack(MyItems.MY_ITEM.get()),
+                ItemRequirement.ItemUseType.CONSUME
+            ))
+        );
+    }
+}
+```
+
+Return `ItemRequirement.NONE` if no items are required in the current state, or `ItemRequirement.INVALID` if the structure cannot be placed at all.