= Cloud documentation
Alexander Söderberg <contact@alexander-soderberg.com>
v0.1.0, 2020-12-30
:sectnums:
:cloud-version: 1.3.0
:toc: left
:toclevels: 3
:icons: font
:hide-uri-scheme:
== Introduction to Cloud
CAUTION: The Cloud documentation is still a work in progress.
Cloud is a command manager and dispatcher for the JVM. Cloud allows you to define commands in
several ways, most notably using command builders, or annotations. Cloud has platform implementations
for many platforms, including Minecraft server software such as Bukkit or Discord bot frameworks
such as JDA.
Cloud allows you to customize the command execution pipeline by injecting custom behaviour along
the entire execution path. All of this will be covered in this document.
This document will first introduce different Cloud concepts using the builder pattern API.
Section 4 will expand upon this by introducing the annotation (declarative) API, which offers
another way of declaring commands.
== Getting Started
Cloud is available through https://search.maven.org/search?q=cloud.commandframework[Maven Central].
[source,xml,subs="attributes,verbatim"]
----
<dependency>
<groupId>cloud.commandframework</groupId>
<artifactId>cloud-core</artifactId>
<version>{cloud-version}</version>
</dependency>
----
If you want to use snapshot builds, then they are available via the Sonatype OSS Snapshot repository:
[source,xml]
----
<repository>
<id>sonatype-snapshots</id>
<url>https://oss.sonatype.org/content/repositories/snapshots</url>
</repository>
----
=== Modules
cloud-core:: Core Cloud API module.
cloud-annotations:: Cloud annotation API.
cloud-services:: Cloud service API. Included in Core.
cloud-tasks:: Cloud scheduling API.
cloud-kotlin-extensions:: Cloud extensions for Kotlin.
cloud-bukkit:: Cloud implementation for the Bukkit API.
cloud-paper:: Extension of cloud-bukkit for the Paper API.
cloud-velocity:: Cloud implementation for the Velocity (1.1.0+) API.
cloud-brigadier:: Cloud utilities for Mojang's Brigadier API.
cloud-bungee:: Cloud implementation for the BungeeCord API.
cloud-jda:: Cloud implementation for the JDA API.
cloud-javacord:: Cloud implementation for the Javacord API.
cloud-pircbotx:: Cloud implementation for the PircBotX framework.
== Core
The core module contains the majority of the API that you will be interacting with when using
Cloud.
=== Command Manager
The first step to any Cloud project is to create a command manager. Each supported platform has
its own command manager, but for the most part they look and behave very similarly. It is possible
to support multiple platforms in the same project.
All command managers have a generic type argument for the command sender type. Most platforms have
their own "native" command sender type, but Cloud allows you to use whatever sender you want, by
supplying a mapping function to the command manager. This sender type will be included in the command context,
which you will be interacting with a lot when using Cloud.
[title="Creating a command manager instance using Bukkit"]
====
This particular example uses `cloud-bukkit`, though most concepts transfer over to the other command mangers.
[source,java]
----
CommandManager<CommandSender> manager = new BukkitCommandManager<>(
/* Owning plugin */ this,
AsynchronousCommandExecutionCoordinator.newBuilder().build(), <1>
Function.identity(), <2>
Function.identity(), <3>
);
----
<1> The execution coordinator handles the coordination of command parsing and execution. You can read more about this
in section 3.6.
<2> Function that maps the platform command sender to your command sender.
<3> Function that maps your command sender to the platform command sender.
====
The command manager is used to register commands, create builders, change command settings, etc.
More information can be found in the CommandManager
https://javadoc.commandframework.cloud/cloud/commandframework/CommandManager.html[JavaDoc].
=== Commands
Commands consist of chains of arguments that are parsed from user input. These arguments
can be either static literals or variables. Variable arguments are parsed into different
types using argument parsers. Variable arguments may be either required, or they can be
optional. Optional arguments may have default values.
[title=Example command structure]
====
[source]
----
/foo bar one
/foo bar two <arg>
/foo <arg> <1>
----
<1> When a variable argument is present next to literals, it will be allowed to catch any
input that isn't caught by the literals. Only one variable may exist at any level, but
there may be many literals.
This example contains three unique commands.
====
=== Argument Types
==== Literals
==== Standard
===== string
===== byte/short/int/long
===== enums
===== boolean
===== compound arguments
==== Custom
==== Flags
=== Suggestions
=== Injection Points
==== Preprocessing
==== Postprocessing
=== Execution Coordinators
=== Command Proxies
=== Permissions
=== Exception Handling
=== Extra
==== Translations
==== Confirmations
==== Help Generation
== Annotations
== Kotlin DSL
== Platforms
=== Minecraft
==== Bukkit
===== Paper
===== Brigadier
==== Sponge
The Sponge implementation is still a work in progress.
==== Fabric
The Fabric implementation is still a work in progress.
=== Discord
==== JDA
==== Javacord
=== IRC
