Update the development documentation

adapters/_DocsAdapter/build.gradle.kts

@@ -0,0 +1,2 @@
+repositories {}
+dependencies {}

adapters/_DocsAdapter/settings.gradle.kts

@@ -0,0 +1,14 @@
+rootProject.name = "DocsAdapter"
+
+includeBuild("../../plugin")
+
+plugins {
+    id("com.gradle.enterprise") version ("3.13.3")
+}
+
+gradleEnterprise {
+    buildScan {
+        termsOfServiceUrl = "https://gradle.com/terms-of-service"
+        termsOfServiceAgree = "yes"
+    }
+}

adapters/_DocsAdapter/src/main/kotlin/com/typewritermc/example/ExampleAdapter.kt

@@ -0,0 +1,17 @@
+package com.typewritermc.example
+
+//<code-block:adapter>
+import me.gabber235.typewriter.adapters.Adapter
+import me.gabber235.typewriter.adapters.TypewriterAdapter
+
+@Adapter("Example", "An example adapter for documentation purposes", "0.0.1")
+object ExampleAdapter : TypewriterAdapter() {
+    override fun initialize() {
+        // Do something when the adapter is initialized
+    }
+
+    override fun shutdown() {
+        // Do something when the adapter is shutdown
+    }
+}
+//</code-block:adapter>

adapters/_DocsAdapter/src/main/kotlin/com/typewritermc/example/entries/cinematic/ExampleCinematicEntry.kt

@@ -0,0 +1,143 @@
+package com.typewritermc.example.entries.cinematic
+
+import me.gabber235.typewriter.adapters.Colors
+import me.gabber235.typewriter.adapters.Entry
+import me.gabber235.typewriter.adapters.modifiers.*
+import me.gabber235.typewriter.entry.Criteria
+import me.gabber235.typewriter.entry.cinematic.SimpleCinematicAction
+import me.gabber235.typewriter.entry.entries.*
+import org.bukkit.entity.Player
+
+//<code-block:cinematic_entry>
+@Entry("example_cinematic", "An example cinematic entry", Colors.BLUE, "material-symbols:cinematic-blur")
+class ExampleCinematicEntry(
+    override val id: String = "",
+    override val name: String = "",
+    override val criteria: List<Criteria> = emptyList(),
+    @Segments(Colors.BLUE, "material-symbols:cinematic-blur")
+    val segments: List<ExampleSegment> = emptyList(),
+) : CinematicEntry {
+    override fun create(player: Player): CinematicAction {
+        return ExampleCinematicAction(player, this)
+    }
+}
+//</code-block:cinematic_entry>
+
+@Entry(
+    "example_with_segment_sizes",
+    "An example cinematic entry with segment sizes",
+    Colors.BLUE,
+    "material-symbols:cinematic-blur"
+)
+class ExampleWithSegmentSizesEntry(
+    override val id: String = "",
+    override val name: String = "",
+    override val criteria: List<Criteria> = emptyList(),
+    //<code-block:cinematic_segment_with_min_max>
+    @Segments(Colors.BLUE, "material-symbols:cinematic-blur")
+    @InnerMin(Min(10))
+    @InnerMax(Max(20))
+    val segments: List<ExampleSegment> = emptyList(),
+    //</code-block:cinematic_segment_with_min_max>
+) : CinematicEntry {
+    //<code-block:cinematic_create_actions>
+    // This will be used when the cinematic is normally displayed to the player.
+    override fun create(player: Player): CinematicAction {
+        return DefaultCinematicAction(player, this)
+    }
+
+    // This is used during content mode to display the cinematic to the player.
+    // It may be null to not show it during simulation.
+    override fun createSimulating(player: Player): CinematicAction? {
+        return SimulatedCinematicAction(player, this)
+    }
+
+    // This is used during content mode to record the cinematic.
+    // It may be null to not record it during simulation.
+    override fun createRecording(player: Player): CinematicAction? {
+        return RecordingCinematicAction(player, this)
+    }
+    //</code-block:cinematic_create_actions>
+}
+
+//<code-block:cinematic_segment>
+data class ExampleSegment(
+    override val startFrame: Int = 0,
+    override val endFrame: Int = 0,
+) : Segment
+//</code-block:cinematic_segment>
+
+//<code-block:cinematic_action>
+class ExampleCinematicAction(
+    val player: Player,
+    val entry: ExampleCinematicEntry,
+) : CinematicAction {
+    override suspend fun setup() {
+        // Initialize variables, spawn entities, etc.
+    }
+
+    override suspend fun tick(frame: Int) {
+        val segment = entry.segments activeSegmentAt frame
+        // Can be null if no segment is active
+
+        // The `frame` parameter is not necessarily next frame: `frame != old(frame)+1`
+
+        // Execute tick logic for the segment
+    }
+
+    override suspend fun teardown() {
+        // Remove entities, etc.
+    }
+
+    override fun canFinish(frame: Int): Boolean = entry.segments canFinishAt frame
+}
+//</code-block:cinematic_action>
+
+//<code-block:cinematic_simple_action>
+class ExampleSimpleCinematicAction(
+    val player: Player,
+    entry: ExampleCinematicEntry,
+) : SimpleCinematicAction<ExampleSegment>() {
+    override val segments: List<ExampleSegment> = entry.segments
+
+    override suspend fun startSegment(segment: ExampleSegment) {
+        super.startSegment(segment) // Keep this
+        // Called when a segment starts
+    }
+
+    override suspend fun tickSegment(segment: ExampleSegment, frame: Int) {
+        super.tickSegment(segment, frame) // Keep this
+        // Called every tick while the segment is active
+        // Will always be called after startSegment and never after stopSegment
+
+        // The `frame` parameter is not necessarily next frame: `frame != old(frame)+1`
+    }
+
+    override suspend fun stopSegment(segment: ExampleSegment) {
+        super.stopSegment(segment) // Keep this
+        // Called when the segment ends
+        // Will also be called if the cinematic is stopped early
+    }
+}
+//</code-block:cinematic_simple_action>
+
+class DefaultCinematicAction(
+    val player: Player,
+    entry: ExampleWithSegmentSizesEntry,
+) : SimpleCinematicAction<ExampleSegment>() {
+    override val segments: List<ExampleSegment> = entry.segments
+}
+
+class SimulatedCinematicAction(
+    val player: Player,
+    entry: ExampleWithSegmentSizesEntry,
+) : SimpleCinematicAction<ExampleSegment>() {
+    override val segments: List<ExampleSegment> = entry.segments
+}
+
+class RecordingCinematicAction(
+    val player: Player,
+    entry: ExampleWithSegmentSizesEntry,
+) : SimpleCinematicAction<ExampleSegment>() {
+    override val segments: List<ExampleSegment> = entry.segments
+}

adapters/_DocsAdapter/src/main/kotlin/com/typewritermc/example/entries/manifest/ExampleAudienceEntry.kt

@@ -0,0 +1,90 @@
+package com.typewritermc.example.entries.manifest
+
+import com.typewritermc.example.entries.trigger.SomeBukkitEvent
+import me.gabber235.typewriter.adapters.Colors
+import me.gabber235.typewriter.adapters.Entry
+import me.gabber235.typewriter.entry.entries.AudienceDisplay
+import me.gabber235.typewriter.entry.entries.AudienceEntry
+import me.gabber235.typewriter.entry.entries.TickableDisplay
+import me.gabber235.typewriter.utils.ThreadType
+import org.bukkit.entity.Player
+import org.bukkit.event.EventHandler
+
+//<code-block:audience_entry>
+@Entry("example_audience", "An example audience entry.", Colors.GREEN, "material-symbols:chat-rounded")
+class ExampleAudienceEntry(
+    override val id: String,
+    override val name: String,
+) : AudienceEntry {
+    override fun display(): AudienceDisplay {
+        return ExampleAudienceDisplay()
+    }
+}
+//</code-block:audience_entry>
+
+//<code-block:audience_display>
+class ExampleAudienceDisplay : AudienceDisplay() {
+    override fun initialize() {
+        // This is called when the first player is added to the audience.
+        super.initialize()
+        // Do something when the audience is initialized
+    }
+
+    override fun onPlayerAdd(player: Player) {
+        // Do something when a player gets added to the audience
+    }
+
+    override fun onPlayerRemove(player: Player) {
+        // Do something when a player gets removed from the audience
+    }
+
+    override fun dispose() {
+        super.dispose()
+        // Do something when the audience is disposed
+        // It will always call onPlayerRemove for all players.
+        // So no player cleanup is needed here.
+    }
+}
+//</code-block:audience_display>
+
+//<code-block:tickable_audience_display>
+// highlight-next-line
+class TickableAudienceDisplay : AudienceDisplay(), TickableDisplay {
+    override fun onPlayerAdd(player: Player) {}
+    override fun onPlayerRemove(player: Player) {}
+
+    // highlight-start
+    override fun tick() {
+        // Do something when the audience is ticked
+        players.forEach { player ->
+            // Do something with the player
+        }
+
+        // This is running asynchronously
+        // If you need to do something on the main thread
+        ThreadType.SYNC.launch {
+            // Though this will run a tick later, to sync with the bukkit scheduler.
+        }
+    }
+    // highlight-end
+}
+//</code-block:tickable_audience_display>
+
+//<code-block:audience_display_with_events>
+class AudienceDisplayWithEvents : AudienceDisplay() {
+    override fun onPlayerAdd(player: Player) {}
+    override fun onPlayerRemove(player: Player) {}
+
+    // highlight-start
+    @EventHandler
+    fun onSomeEvent(event: SomeBukkitEvent) {
+        // Do something when the event is triggered
+        // This will trigger for all players, not just the ones in the audience.
+        // So we need to check if the player is in the audience.
+        if (event.player in this) {
+            // Do something with the player
+        }
+    }
+    // highlight-end
+}
+//</code-block:audience_display_with_events>

adapters/_DocsAdapter/src/main/kotlin/com/typewritermc/example/entries/static/ExampleArtifactEntry.kt

@@ -0,0 +1,26 @@
+package com.typewritermc.example.entries.static
+
+import me.gabber235.typewriter.adapters.Colors
+import me.gabber235.typewriter.adapters.Entry
+import me.gabber235.typewriter.entry.AssetManager
+import me.gabber235.typewriter.entry.Ref
+import me.gabber235.typewriter.entry.entries.ArtifactEntry
+import org.koin.java.KoinJavaComponent
+
+//<code-block:artifact_entry>
+@Entry("example_artifact", "An example artifact entry.", Colors.BLUE, "material-symbols:home-storage-rounded")
+class ExampleArtifactEntry(
+    override val id: String = "",
+    override val name: String = "",
+    override val artifactId: String = "",
+) : ArtifactEntry
+//</code-block:artifact_entry>
+
+//<code-block:artifact_access>
+suspend fun accessArtifactData(ref: Ref<out ArtifactEntry>) {
+    val assetManager = KoinJavaComponent.get<AssetManager>(AssetManager::class.java)
+    val entry = ref.get() ?: return
+    val content: String? = assetManager.fetchAsset(entry)
+    // Do something with the content
+}
+//</code-block:artifact_access>

adapters/_DocsAdapter/src/main/kotlin/com/typewritermc/example/entries/static/ExampleAssetEntry.kt

@@ -0,0 +1,26 @@
+package com.typewritermc.example.entries.static
+
+import me.gabber235.typewriter.adapters.Colors
+import me.gabber235.typewriter.adapters.Entry
+import me.gabber235.typewriter.entry.AssetManager
+import me.gabber235.typewriter.entry.Ref
+import me.gabber235.typewriter.entry.entries.AssetEntry
+import org.koin.java.KoinJavaComponent
+
+//<code-block:asset_entry>
+@Entry("example_asset", "An example asset entry.", Colors.BLUE, "material-symbols:home-storage-rounded")
+class ExampleAssetEntry(
+    override val id: String = "",
+    override val name: String = "",
+    override val path: String = "",
+) : AssetEntry
+//</code-block:asset_entry>
+
+//<code-block:asset_access>
+suspend fun accessAssetData(ref: Ref<out AssetEntry>) {
+    val assetManager = KoinJavaComponent.get<AssetManager>(AssetManager::class.java)
+    val entry = ref.get() ?: return
+    val content: String? = assetManager.fetchAsset(entry)
+    // Do something with the content
+}
+//</code-block:asset_access>

adapters/_DocsAdapter/src/main/kotlin/com/typewritermc/example/entries/static/ExampleSoundIdEntry.kt

@@ -0,0 +1,14 @@
+package com.typewritermc.example.entries.static
+
+import me.gabber235.typewriter.adapters.Colors
+import me.gabber235.typewriter.adapters.Entry
+import me.gabber235.typewriter.entry.entries.SoundIdEntry
+
+//<code-block:sound_id_entry>
+@Entry("example_sound", "An example sound entry.", Colors.BLUE, "icon-park-solid:volume-up")
+class ExampleSoundIdEntry(
+    override val id: String = "",
+    override val name: String = "",
+    override val soundId: String = "",
+) : SoundIdEntry
+//</code-block:sound_id_entry>

adapters/_DocsAdapter/src/main/kotlin/com/typewritermc/example/entries/static/ExampleSoundSourceEntry.kt

@@ -0,0 +1,20 @@
+package com.typewritermc.example.entries.static
+
+import me.gabber235.typewriter.adapters.Colors
+import me.gabber235.typewriter.adapters.Entry
+import me.gabber235.typewriter.entry.entries.SoundSourceEntry
+import net.kyori.adventure.sound.Sound
+
+//<code-block:sound_source_entry>
+@Entry("example_sound_source", "An example sound source entry.", Colors.BLUE, "ic:round-spatial-audio-off")
+class ExampleSoundSourceEntry(
+    override val id: String = "",
+    override val name: String = "",
+) : SoundSourceEntry {
+    override fun getEmitter(): Sound.Emitter {
+        // Return the emitter that should be used for the sound.
+        // A bukkit entity can be used here.
+        return Sound.Emitter.self()
+    }
+}
+//</code-block:sound_source_entry>

adapters/_DocsAdapter/src/main/kotlin/com/typewritermc/example/entries/static/ExampleSpeakerEntry.kt

@@ -0,0 +1,16 @@
+package com.typewritermc.example.entries.static
+
+import me.gabber235.typewriter.adapters.Colors
+import me.gabber235.typewriter.adapters.Entry
+import me.gabber235.typewriter.entry.entries.SpeakerEntry
+import me.gabber235.typewriter.utils.Sound
+
+//<code-block:speaker_entry>
+@Entry("example_speaker", "An example speaker entry.", Colors.BLUE, "ic:round-spatial-audio-off")
+class ExampleSpeakerEntry(
+    override val id: String = "",
+    override val name: String = "",
+    override val displayName: String = "",
+    override val sound: Sound = Sound.EMPTY,
+) : SpeakerEntry
+//</code-block:speaker_entry>