From 284e55e93d99e06dd588553d1afcb94b8f3018ff Mon Sep 17 00:00:00 2001 From: Gabber235 Date: Sun, 10 Dec 2023 14:00:17 +0100 Subject: [PATCH] Add additional entry documentation --- documentation/docs/develop/01-index.mdx | 2 +- .../develop/02-adapters/03-entries/index.mdx | 2 +- .../03-entries/static/artifact.mdx | 38 +++++++++++++++++++ .../02-adapters/03-entries/static/asset.mdx | 13 ++++++- .../03-entries/static/sound_id.mdx | 23 +++++++++++ .../02-adapters/03-entries/static/speaker.mdx | 27 +++++++++++++ .../docs/develop/02-adapters/index.mdx | 2 +- 7 files changed, 102 insertions(+), 5 deletions(-) create mode 100644 documentation/docs/develop/02-adapters/03-entries/static/artifact.mdx create mode 100644 documentation/docs/develop/02-adapters/03-entries/static/sound_id.mdx create mode 100644 documentation/docs/develop/02-adapters/03-entries/static/speaker.mdx diff --git a/documentation/docs/develop/01-index.mdx b/documentation/docs/develop/01-index.mdx index fe6ba55659..1c9255e49e 100644 --- a/documentation/docs/develop/01-index.mdx +++ b/documentation/docs/develop/01-index.mdx @@ -5,4 +5,4 @@ Lastly there is the UI. This is written in Flutter and is the most complex part :::danger important This part of the documentation is still under construction. If you want to help, please contact us on [Discord](https://discord.gg/HtbKyuDDBw). -::: \ No newline at end of file +::: diff --git a/documentation/docs/develop/02-adapters/03-entries/index.mdx b/documentation/docs/develop/02-adapters/03-entries/index.mdx index 20673361c1..d27b09360b 100644 --- a/documentation/docs/develop/02-adapters/03-entries/index.mdx +++ b/documentation/docs/develop/02-adapters/03-entries/index.mdx @@ -4,7 +4,7 @@ purpose in crafting immersive player experiences. This documentation explains the roles and functionalities of these entry types, providing clear guidance for developers on how to effectively use them. ## Base Entry Interfaces -There are three base interfaces that all entries extend atleast one of. These are: +There are three base interfaces that all entries extend one of. These are: 1. **StaticEntry**: Represents static pages. These are used for content that does not change dynamically or trigger any actions. Examples include static text or images. 2. **TriggerEntry**: Designed for entries that initiate other actions or events. These entries can trigger one or more additional entries, making them crucial for interactive sequences. 3. **CinematicEntry**: Used for cinematic experiences. These entries are ideal for creating immersive story-driven sequences that engage players in a more visually dynamic way. diff --git a/documentation/docs/develop/02-adapters/03-entries/static/artifact.mdx b/documentation/docs/develop/02-adapters/03-entries/static/artifact.mdx new file mode 100644 index 0000000000..9378e18596 --- /dev/null +++ b/documentation/docs/develop/02-adapters/03-entries/static/artifact.mdx @@ -0,0 +1,38 @@ +# ArtifactEntry + +The `ArtifactEntry` is a specialized interface derived from `AssetEntry`. +Its primary purpose is to handle artifacts, which are assets generated by the plugins/adapters itself. +Unlike standard assets, artifacts are usually dynamic and created during runtime. +This makes them particularly useful for storing data that changes based on player interactions or game events. + +An essential feature of `ArtifactEntry` is its unique `artifactId`. +This identifier must remain constant once assigned and is used to reference the artifact within the plugin. + +## Usage + +Here's a generic example of creating and using an `ArtifactEntry`: + +### Defining an ArtifactEntry + +```kotlin +@Entry("example_artifact", "An example artifact entry.", Colors.BLUE, Icons.ARROW) +class ExampleArtifactEntry( + override val id: String = "", + override val name: String = "", + override val artifactId: String = "", +) : ArtifactEntry +``` + +### Accessing the Artifact's Content +```kotlin +import org.koin.java.KoinJavaComponent.get + +val assetManager = get(AssetManager::class.java) + +val id = // ID of the entry +val entry = Query.findById(id) +val content: String = assetManager.fetchAsset(entry) +``` + +In this example, `ExampleArtifactEntry` is defined as an artifact with a unique identifier. The `assetManager.fetchAsset` method is then used to retrieve the content of the artifact, based on its `artifactId`. + diff --git a/documentation/docs/develop/02-adapters/03-entries/static/asset.mdx b/documentation/docs/develop/02-adapters/03-entries/static/asset.mdx index 68d144d055..efa80c3f7e 100644 --- a/documentation/docs/develop/02-adapters/03-entries/static/asset.mdx +++ b/documentation/docs/develop/02-adapters/03-entries/static/asset.mdx @@ -1,10 +1,13 @@ # AssetEntry -The AssetEntry is a specialized interface that extends the StaticEntry in the TypeWriter Spigot plugin. +The AssetEntry is a specialized interface that extends the `StaticEntry`. It is primarily used for handling static assets within the game. Assets can include various types of files such as images, sounds, or other external resources that are crucial to enhancing the game environment and player experience. The key attribute of AssetEntry is the path, which specifies the location of the asset. ## Usage +Here's a generic example of creating and using an `AssetEntry`: + +### Defining an AssetEntry ```kotlin @Entry("example_asset", "An example asset entry.", Colors.PINK, Icons.PERSON_WALKING) class ExampleAssetEntry( @@ -12,9 +15,15 @@ class ExampleAssetEntry( ): AssetEntry ``` +### Accessing the Artifact's Content + To get the asset from the entry, you can use the following code: ```kotlin +import org.koin.java.KoinJavaComponent.get + +val assetManager = get(AssetManager::class.java) + val id = // ID of the entry val entry = Query.findById(id) -val path = entry.path +val content: String = assetManager.fetchAsset(entry) ``` diff --git a/documentation/docs/develop/02-adapters/03-entries/static/sound_id.mdx b/documentation/docs/develop/02-adapters/03-entries/static/sound_id.mdx new file mode 100644 index 0000000000..0a3ce8dc18 --- /dev/null +++ b/documentation/docs/develop/02-adapters/03-entries/static/sound_id.mdx @@ -0,0 +1,23 @@ +# SoundIdEntry + +The `SoundIdEntry` is an interface derived from `StaticEntry`, specifically designed for managing custom sounds within the TypeWriter Spigot plugin. +If a server is using a custom resource pack, the `SoundIdEntry` can be used to add a reference to a custom sound within the resource pack. + +## Usage +```kotlin +@Entry("example_sound", "An example sound entry.", Colors.GREEN, Icons.VOLUME_HIGH) +class ExampleSoundIdEntry( + override val id: String, + override val name: String, + override val soundId: String, +) : SoundIdEntry +``` + +Normally a `SoundIdEntry` handled by the interface when an entry needs a sound. +If you ever would need to access the sound ID directly, it can be done like this: + +```kotlin +val id = // ID of the custom sound +val entry = Query.findById(id) +val customSound = entry.soundId +``` diff --git a/documentation/docs/develop/02-adapters/03-entries/static/speaker.mdx b/documentation/docs/develop/02-adapters/03-entries/static/speaker.mdx new file mode 100644 index 0000000000..da9b580cdf --- /dev/null +++ b/documentation/docs/develop/02-adapters/03-entries/static/speaker.mdx @@ -0,0 +1,27 @@ +# SpeakerEntry + +The `SpeakerEntry` is a specialized interface extending the `EntityEntry`. +It is designed to enhance dialogues in the game by associating non-player characters (NPCs) with specific names and sounds. +This feature is pivotal for creating more immersive and interactive storytelling experiences in Minecraft. + +## Usage +```kotlin +@Entry("example_speaker", "An example speaker entry.", Colors.BLUE, Icons.PERSON_TALKING) +class ExampleSpeakerEntry( + override val id: String = "", + override val name: String = "", + override val displayName: String = "", + override val sound: Sound = Sound.EMPTY, +) : SpeakerEntry +``` + +This speaker can be used by users in various dialogues and interactions within the game. +Normally, you never need to access the `SpeakerEntry` directly, as it is automatically handled by the `DialogueSequence`. +If you ever do need to access the `SpeakerEntry`, you can do so: + +```kotlin +val id = // ID of the speaker +val entry = Query.findById(id) +val name = entry.displayName +val sound = entry.sound +``` diff --git a/documentation/docs/develop/02-adapters/index.mdx b/documentation/docs/develop/02-adapters/index.mdx index a1f4b804d3..51ffb40ff2 100644 --- a/documentation/docs/develop/02-adapters/index.mdx +++ b/documentation/docs/develop/02-adapters/index.mdx @@ -3,7 +3,7 @@ TypeWriter is a dynamic platform that supports the development of adapters, which are modular components enhancing the overall functionality. Adapters are self-contained, easily shareable, and integrate smoothly into the TypeWriter system. This guide is tailored to guide you through the process of creating an adapter, suitable for both beginners and experienced developers. :::info -It is highly recommended to write adapters in Kotlin, as it is the primary language of TypeWriter. However, it is also possible to write adapters in Java, as long as the adapter is compiled into a `.jar` file. +It is highly recommended to write adapters in Kotlin, as it is the primary language of TypeWriter. Though, it is possible to write adapters in Java, not all features are usable in Java. ::: ## Guides