-
-
Notifications
You must be signed in to change notification settings - Fork 57
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #102 from gabber235/feature/documentation
Documentation Update
- Loading branch information
Showing
48 changed files
with
1,448 additions
and
587 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
106 changes: 106 additions & 0 deletions
106
documentation/docs/develop/02-adapters/02-getting_started.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,106 @@ | ||
| --- | ||
| title: Getting Started | ||
| --- | ||
|
|
||
| # Creating an Adapter | ||
| ## Introduction | ||
| 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. | ||
|
|
||
| ## Prerequisites | ||
| - Java Development Kit (JDK) 17 or higher. | ||
| - An Integrated Development Environment (IDE) such as IntelliJ IDEA or Eclipse. | ||
| - A basic understanding of Gradle and the Spigot API. | ||
|
|
||
| ## Step 1: Setting Up a Gradle Project | ||
| Begin by establishing a Gradle project for your TypeWriter adapter. Below is a comprehensive setup for your `build.gradle.kts`: | ||
|
|
||
| ```kotlin title="build.gradle.kts" | ||
| plugins { | ||
| kotlin("jvm") version "1.8.20" | ||
| id("com.github.johnrengelman.shadow") version "8.1.1" | ||
| } | ||
|
|
||
| // Replace with your own information | ||
| group = "me.yourusername" | ||
| version = "0.0.1" | ||
|
|
||
| repositories { | ||
| maven("https://jitpack.io") | ||
| mavenCentral() | ||
| maven("https://hub.spigotmc.org/nexus/content/repositories/snapshots/") | ||
| maven("https://oss.sonatype.org/content/groups/public/") | ||
| maven("https://libraries.minecraft.net/") | ||
| maven("https://repo.papermc.io/repository/maven-public/") | ||
| maven("https://repo.codemc.io/repository/maven-snapshots/") | ||
| maven("https://repo.opencollab.dev/maven-snapshots/") | ||
|
|
||
| // Add other necessary repositories | ||
| } | ||
|
|
||
| dependencies { | ||
| compileOnly(kotlin("stdlib")) | ||
| compileOnly("io.papermc.paper:paper-api:1.20.1-R0.1-SNAPSHOT") | ||
| compileOnly("com.github.gabber235:typewriter:main-SNAPSHOT") // Latest release version | ||
|
|
||
| // Already included in the TypeWriter plugin but still needed for compilation | ||
| compileOnly("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.0-RC") | ||
| compileOnly("com.github.dyam0:LirandAPI:96cc59d4fb") | ||
| compileOnly("net.kyori:adventure-api:4.13.1") | ||
| compileOnly("net.kyori:adventure-text-minimessage:4.13.1") | ||
|
|
||
| // Add other dependencies as needed | ||
| } | ||
|
|
||
| java { | ||
| sourceCompatibility = JavaVersion.VERSION_17 | ||
| targetCompatibility = JavaVersion.VERSION_17 | ||
| } | ||
| ``` | ||
|
|
||
| Ensure to replace placeholders like `me.yourusername` with your project details. | ||
|
|
||
| ### Choosing the TypeWriter Version | ||
| Select the appropriate TypeWriter dependency version: | ||
| For stable and tested features, use the latest release version: | ||
| ```kotlin | ||
| compileOnly("com.github.gabber235:typewriter:main-SNAPSHOT") | ||
| ``` | ||
| This is suitable for most development needs and is recommended for general adapter creation. | ||
|
|
||
| If you need the latest features and improvements (which might be unstable), use the latest development version: | ||
| ```kotlin | ||
| compileOnly("com.github.gabber235:typewriter:develop-SNAPSHOT") | ||
| ``` | ||
| Note that this version may include changes that are not yet fully tested or documented. | ||
|
|
||
| If you need a specific version, visit the [JitPack page](https://jitpack.io/#gabber235/typewriter) and select the version you need. | ||
|
|
||
| ## Step 2: Creating an Adapter Class | ||
| After setting up your project, create an adapter class. Here's an example: | ||
| kotlin title="ExampleAdapter.kt" | ||
| ```kotlin | ||
| import me.gabber235.typewriter.adapters.Adapter | ||
| import me.gabber235.typewriter.adapters.TypewriteAdapter | ||
|
|
||
| @Adapter("Example", "An example adapter for documentation purposes", "0.0.1") | ||
| object ExampleAdapter : TypewriteAdapter() { | ||
| override fun initialize() { | ||
| // Any initializations needed to run the adapter. | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
|
|
||
| ## Step 3: Building the Adapter | ||
| After creating the adapter class, build the adapter. This can be done by running the `shadowJar` Gradle task. | ||
| This will generate a JAR file in the `build/libs` directory. | ||
| This JAR file can be used as an adapter in TypeWriter. | ||
| Place the JAR file in the `plugins/TypeWriter/adapters` directory and restart the server. | ||
| Typewriter will automatically load the adapter and run it. | ||
|
|
||
| If any problems occur, check the console for errors and ensure that the adapter is properly configured. | ||
| If you need help, join the [Discord server](https://discord.gg/HtbKyuDDBw) and ask for help. | ||
|
|
||
| ## What's Next? | ||
| After creating an adapter, you can start adding features to it. | ||
| Check out the [Creating Entries](creating-entries) guide to learn how to add entries to your adapter. |
113 changes: 113 additions & 0 deletions
113
documentation/docs/develop/02-adapters/03-entries/cinematic/index.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,113 @@ | ||
| # CinematicEntry | ||
|
|
||
| The `CinematicEntry` does not have any decentends, but is very customizable. When a entry is needed in a cinematic page, it needs to inherid this. | ||
|
|
||
| `CinematicEntry` works by having at least 1 list of `Segment`'s. Segments are the parts of the cinematic and may have sub-properties defined. A segment needs to have at least a `startFrame` and `endFrame` which are the integers of the frames. | ||
|
|
||
| Frames are the ticks in a second. So there are 20 frames in a second. A cinematic takes as long as the latest `endFrame` of a segment from all it's entries. | ||
|
|
||
| Segments are defined in the entry using the `@Segments` annotation. And it needs to be a list of `Segment`'s. | ||
|
|
||
|
|
||
| :::info | ||
| A `CinematicEntry` can have multiple different segment tracks. | ||
| For example, a cinematic entry may have a `TextSegment` and a `SoundSegment`. | ||
|
|
||
| Though this is supported in the plugin, it is not yet implemented in the cinematic editor. | ||
| If you need this, reach out to me on [Discord](https://discord.gg/HtbKyuDDBw). | ||
| ::: | ||
|
|
||
| As entries are not allowed to have any state, we create a `CinematicAction` everytime a entry is used in a cinematic for a player. | ||
|
|
||
| ## Usage | ||
| ```kotlin | ||
| @Entry("example_cinematic", "An example cinematic entry.", Colors.CYAN, Icons.TERMINAL) | ||
| class ExampleCinematicEntry( | ||
| override val id: String, | ||
| override val name: String, | ||
| override val criteria: List<Criteria>, | ||
| @Segments(Colors.CYAN, Icons.TERMINAL) | ||
| override val segments: List<ExampleSegment>, | ||
| ): CinematicEntry { | ||
| override fun create(player: Player): CinematicAction { | ||
| return ExampleCinematicAction(player, this) | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| Segments sometimes need a minimum or maximum duration. This can be done using the `@InnerMin` and `@InnerMax` annotations. | ||
|
|
||
| ```kotlin | ||
| @Segments(Colors.CYAN, Icons.TERMINAL) | ||
| @InnerMin(Min(10)) | ||
| @InnerMax(Max(20)) | ||
| override val segments: List<ExampleSegment>, | ||
| ``` | ||
|
|
||
| This will make sure that the segment will be at least 10 frames long and at most 20 frames long. | ||
|
|
||
| ### ExampleSegment | ||
| ```kotlin | ||
| data class ExampleSegment( | ||
| override val startFrame: Int, | ||
| override val endFrame: Int, | ||
| ): Segment | ||
| ``` | ||
|
|
||
| ### ExampleCinematicAction | ||
|
|
||
| The `CinematicAction` is the action that is created when a cinematic is started. It is used to keep track of the current frame and to execute the segments. | ||
| There are a few different lifecycle methods that can be used. | ||
|
|
||
| - `setup()` is called when the cinematic is created. This is the place to initialize any variables, spawn entities, etc. | ||
| - `tick(frame: Int)` is called every frame. This is the place to execute the segments. It is even executed when no segments are active. | ||
| - `teardown()` is called when the cinematic is finished. This is the place to remove any entities, etc. | ||
| - `canFinish(frame: Int)` the only method that needs to be implemented. It is used by the `CinematicSequence` to determine if the cinematic is finished. | ||
|
|
||
| If you need all the customization, you can can implement the `CinematicAction` directly: | ||
|
|
||
| ```kotlin | ||
| class ExampleCinematicAction( | ||
| override val player: Player, | ||
| override val entry: ExampleCinematicEntry, | ||
| ): CinematicAction { | ||
| override fun setup() { | ||
| // Initialize variables, spawn entities, etc. | ||
| } | ||
|
|
||
| override fun tick(frame: Int) { | ||
| val segment = entry.segments activeSegmentAt frame | ||
| // Can be null if no segment is active | ||
|
|
||
| // Execute segments | ||
| } | ||
|
|
||
| override fun teardown() { | ||
| // Remove entities, etc. | ||
| } | ||
|
|
||
| override fun canFinish(frame: Int): Boolean = entry.segments canFinishAt frame | ||
| } | ||
| ``` | ||
|
|
||
| ### SimpleCinematicAction | ||
| Sometimes you don't need all the customization and flexiblity. If you only care about 1 segment track, and only need to do something when a segment starts or ends, you can use the `SimpleCinematicAction`. | ||
|
|
||
| ```kotlin | ||
| class ExampleCinematicAction( | ||
| override val player: Player, | ||
| override val entry: ExampleCinematicEntry, | ||
| ): SimpleCinematicAction<ExampleSegment>() { | ||
| override val segments: List<ExampleSegment> = entry.segments | ||
|
|
||
| override suspend fun startSegment(segment: ExampleSegment) { | ||
| // Called when a segment starts | ||
| } | ||
|
|
||
| override suspend fun endSegment(segment: ExampleSegment) { | ||
| // Called when a segment ends | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
|
|
68 changes: 68 additions & 0 deletions
68
documentation/docs/develop/02-adapters/03-entries/index.mdx
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,68 @@ | ||
| # Create Entries | ||
| Creating adapters for the TypeWriter Spigot plugin involves working with various entry types, each serving a specific | ||
| 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 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. | ||
|
|
||
|
|
||
| ### 1. StaticEntry | ||
| - **AssetEntry**: Handles external assets, like images or files. | ||
| - **ArtifactEntry**: Manages plugin-generated assets, such as JSON files. | ||
| - **EntityEntry**: Serves as a base for static entities in the game. | ||
| - **SpeakerEntry**: Extends EntityEntry for entities capable of speaking, with defined display names and sounds. | ||
| - **FactEntry**: Represents static facts or data points. | ||
| - **SoundIdEntry**: Holds identifiers for specific sounds. | ||
| - **SoundSourceEntry**: Deals with the sources of sound emissions. | ||
|
|
||
| ### 2. TriggerEntry | ||
| - **EventEntry**: A base for entries that are event-driven. | ||
| - **CustomCommandEntry**: Extends EventEntry to allow for the creation of custom in-game commands. | ||
|
|
||
| #### 2a. TriggerableEntry (an extension of TriggerEntry) | ||
| These are entries that can be triggered by other entries. They are the most common type of entry, and are used for creating interactive sequences. | ||
| - **DialogueEntry**: Specialized for dialogues with specific speakers, enhancing NPC interactions. | ||
| - **ActionEntry**: Executes actions based on player interactions, capable of modifying facts or triggering events. | ||
| - **CustomTriggeringActionEntry**: A variant of ActionEntry, allowing for custom trigger mechanisms and manual triggering of actions. | ||
|
|
||
| ### 3. CinematicEntry | ||
| - Primarily used for crafting cinematic experiences in-game, this base interface doesn't have listed specialized interfaces, but it's pivotal for creating story-driven, visually dynamic sequences. | ||
|
|
||
|
|
||
| ## Implementation and Usage | ||
| Each interface is designed with specific tags and methods to facilitate unique interactions within the TypeWriter plugin. | ||
| Implementing these interfaces allows developers to craft a wide range of player experiences, from simple static displays to complex, multi-step interactive quests and dialogues. | ||
|
|
||
| For instance, a TriggerableEntry can be used to set up a quest that only activates under certain conditions, while a DialogueEntry can bring an NPC to life with personalized dialogues. | ||
| Similarly, an ActionEntry can be used to create dynamic effects that change based on player actions, and a CinematicEntry can be used to create a visually dynamic story sequence. | ||
|
|
||
|
|
||
| ### Defining a Entry | ||
| Typewriter takes care of the heavy lifting when it comes to creating and using entries. | ||
| Developers only need to define the entry's class and its fields (and sometimes additional methods). The rest is handled by Typewriter. From scanning the adapters jar file for all the different entry classes to triggering them. | ||
|
|
||
| To define an entry, it needs to meet the following requirements: | ||
| 1. It must be a class that implements one of the base entry interfaces. | ||
| 2. It must have a no-args constructor. | ||
| 3. It must have a `@Entry` annotation with all the required fields. | ||
|
|
||
| The `@Entry` annotation is used to define the entry's type, name, and other properties. It has the following fields: | ||
| - **name**: The name of the entry. This is used to identify the entry. | ||
| - **description**: A short description of the entry. | ||
| - **color**: The color of the entry in the editor. It can be one from the `Colors` class or a hex color code string. | ||
| - **icon**: The icon of the entry in the editor. It can be one from the `Icons` class. All icons are from [Font Awesome](https://fontawesome.com/search?o=r&m=free) free collection. | ||
|
|
||
| To find out specific requirements for each entry type, check the documentation for the entry's interface. | ||
|
|
||
| :::caution | ||
| Enties are not allowed to have any state. This means that there can't be any fields that are not final. | ||
| ::: | ||
|
|
||
| --- | ||
|
|
||
| In summary, these entry interfaces form the backbone of the TypeWriter plugin's functionality, offering a robust framework for creating immersive and interactive content within Minecraft. | ||
| By understanding and utilizing these interfaces, developers can greatly enhance the player experience, making it more engaging and dynamic. |
1 change: 1 addition & 0 deletions
1
documentation/docs/develop/02-adapters/03-entries/static/_category_.yml
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| label: Static Entries |
Oops, something went wrong.