diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 000000000..2781f6d58 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,9 @@ +############### +# folder # +############### +/**/DROP/ +/**/TEMP/ +/**/packages/ +/**/bin/ +/**/obj/ +_site diff --git a/docs/Dockerfile b/docs/Dockerfile new file mode 100644 index 000000000..94c4d78f1 --- /dev/null +++ b/docs/Dockerfile @@ -0,0 +1,22 @@ +FROM mono:latest + +RUN apt-get update -y && apt-get install -y unzip + +RUN mkdir -p /docfx +WORKDIR /docfx +RUN curl -L https://github.com/dotnet/docfx/releases/download/v2.43.3/docfx.zip -O \ + && unzip docfx.zip \ + && chmod +r /docfx + +RUN echo "#!/bin/bash" >> /usr/local/bin/docfx \ + && echo "mono /docfx/docfx.exe \"\$@\"" >> /usr/local/bin/docfx \ + && chmod +x /usr/local/bin/docfx + +RUN mkdir -p /srv/project \ + && useradd -u 1000 docfx \ + && chown docfx:docfx /srv/project + +USER docfx +WORKDIR /srv/project + +ENTRYPOINT ["docfx"] \ No newline at end of file diff --git a/docs/api/.gitignore b/docs/api/.gitignore new file mode 100644 index 000000000..f798527e6 --- /dev/null +++ b/docs/api/.gitignore @@ -0,0 +1,5 @@ +############### +# temp file # +############### +*.yml +.manifest diff --git a/docs/api/index.md b/docs/api/index.md new file mode 100644 index 000000000..fff663be0 --- /dev/null +++ b/docs/api/index.md @@ -0,0 +1,2 @@ +# PLACEHOLD +TODO: Add .NET projects to the *src* folder and run `docfx` to generate **REAL** *API Documentation*! diff --git a/docs/docfx.json b/docs/docfx.json new file mode 100644 index 000000000..f2be8312d --- /dev/null +++ b/docs/docfx.json @@ -0,0 +1,63 @@ +{ + "metadata": [ + { + "src": [ + { + "files": [ + ] + } + ], + "dest": "api", + "disableGitFeatures": false, + "disableDefaultFilter": false + } + ], + "build": { + "content": [ + { + "files": [ + "api/**.yml", + "api/index.md" + ] + }, + { + "files": [ + "guide/**.md", + "guide/**/toc.yml", + "toc.yml", + "*.md" + ] + } + ], + "resource": [ + { + "files": [ + "images/**" + ] + } + ], + "overwrite": [ + { + "files": [ + "apidoc/**.md" + ], + "exclude": [ + "obj/**", + "_site/**" + ] + } + ], + "dest": "_site", + "globalMetadataFiles": [], + "fileMetadataFiles": [], + "template": [ + "default" + ], + "postProcessors": [], + "markdownEngineName": "markdig", + "noLangKeyword": false, + "keepFileLink": false, + "cleanupCacheHistory": false, + "disableGitFeatures": false + } +} \ No newline at end of file diff --git a/docs/guide/getting-started/01-setting-up-environment.md b/docs/guide/getting-started/01-setting-up-environment.md new file mode 100644 index 000000000..b592ebe23 --- /dev/null +++ b/docs/guide/getting-started/01-setting-up-environment.md @@ -0,0 +1,8 @@ +# Setting up a development environment + +## Prerequisites + +- **RuneScape game data**: The cache files containing the game data for release 377 of RuneScape. + +- **JDK 8+**: An installation of the JDK is needed to run Gradle build tasks and run the server. + diff --git a/docs/guide/getting-started/02-running-apollo.md b/docs/guide/getting-started/02-running-apollo.md new file mode 100644 index 000000000..912cb9552 --- /dev/null +++ b/docs/guide/getting-started/02-running-apollo.md @@ -0,0 +1,84 @@ +This is a short guide to getting a copy of Apollo from our VCS and +running a server able to accept connections from a game client. It +assumes you’re starting fresh and have no local copy of Apollo. + +Requirements +============ + +You should be familiar with running programs on the UNIX shell or +Windows command prompt. There is also a short list of prerequisites +below needed to complete this guide. + +- Git +- Gradle +- Java 8 +- RuneScape r377 game data files [1] + +Getting Apollo +============== + +> **Note** +> +> Apollo is still in a development phase and has no current stable +> release, so to run the server we need to build it from sources first. + +The URL for the Apollo git repository is +. You can clone this using +the `git` command-line client or by using the [GitHub desktop +client](https://help.github.com/desktop/guides/contributing-to-projects/cloning-a-repository-from-github-desktop/). + +``` +> $ git clone +``` + +If using the command line client, the repository will now be under a +folder named *apollo* and is ready to build. When complete open a shell +or Windows command prompt in that directory and move to the next step. + +Building Apollo +=============== + +Apollo uses Gradle build scripts as it’s build system. To build it, +create a command prompt or shell in the Apollo repository folder and +run: + +``` +> $ ./gradlew assemble genRsa +``` + +This will build the core server with the content plugins and run their +respective tests. This process takes around a minute to complete and +when done will generate and output a set of RSA key parameters used by +connecting clients to encrypt their credentials. Save these for later. + +Starting Apollo +=============== + +The last dependency is putting the game data in a location where the +server can find it. By default Apollo looks under `data/fs` in the root +directory for a folder matching the release number. Apollo supports +release 377, so in our case we want the directory structure to look like +this: + +``` +data/fs +└── 377 + ├── jingle1.mid + ├── main_file_cache.dat + ├── main_file_cache.idx0 + ├── main_file_cache.idx1 + ├── main_file_cache.idx2 + ├── main_file_cache.idxN +``` + +Now that everything is in place we can use the Gradle task to boot the +server. + +``` +> $ gradle server:run +``` + +After booting Apollo will have loaded the game data and be ready to accept connections. + +[1] We are unable to provide user-end assets like the game data or +client due to copyright restrictions. diff --git a/docs/guide/introduction/01-what-is-apollo.md b/docs/guide/introduction/01-what-is-apollo.md new file mode 100644 index 000000000..c927c78a5 --- /dev/null +++ b/docs/guide/introduction/01-what-is-apollo.md @@ -0,0 +1,13 @@ +# What is Apollo? + +Apollo is a high-performance, modular RuneScape emulator with a +collection of utilities for managing data files and plugins. Apollo +targets revision 377 of the RuneScape client from late 2006. It aims to +achieve parity with the game server of that time and preserve the +history of the game in doing so. + +## Is Apollo free? + +Apollo is open source and made available under the ISC license. The git +repository for the project is hosted under the [Apollo RSPS +organization](https://github.com/apollo-rsps) on GitHub. diff --git a/docs/guide/plugins/01-what-is-a-plugin.md b/docs/guide/plugins/01-what-is-a-plugin.md new file mode 100644 index 000000000..0a0868b85 --- /dev/null +++ b/docs/guide/plugins/01-what-is-a-plugin.md @@ -0,0 +1 @@ +# What is a plugin? \ No newline at end of file diff --git a/docs/src/docs/asciidoc/plugins/creating-a-plugin.adoc b/docs/guide/plugins/02-creating-a-plugin.md similarity index 92% rename from docs/src/docs/asciidoc/plugins/creating-a-plugin.adoc rename to docs/guide/plugins/02-creating-a-plugin.md index 4548ebf7f..ef0636673 100644 --- a/docs/src/docs/asciidoc/plugins/creating-a-plugin.adoc +++ b/docs/guide/plugins/02-creating-a-plugin.md @@ -1,7 +1,6 @@ -[[getting-started-with-plugins]] -= Creating a plugin +# Creating a plugin -Apollo's plugins are written in http://kotlinlang.org[Kotlin] and are +Apollo's plugins are written in [Kotlin](http://kotlinlang.org) and are primarily for content, not core code (if you aren't sure where your code should go, ask in irc). Note that this tutorial assumes some familiarity with Kotlin, although good Java knowledge will probably be enough. @@ -9,11 +8,10 @@ with Kotlin, although good Java knowledge will probably be enough. Note: This tutorial is for developing Plugins for the kotlin-experiments branch prior to the release of the Kotlin plugin system for Apollo. -[[create-the-working-environment]] -== Create a working environment +## Create a working environment The project maintainers strongly recommend -https://www.jetbrains.com/idea/[IntelliJ IDEA]. +[IntelliJ IDEA](https://www.jetbrains.com/idea/). After starting IDEA, select *checkout project* with the URL: https://github.com/apollo-rsps/apollo.git and continue. Make sure to @@ -24,8 +22,7 @@ use the navigation bar at the top and 'VCS > Git > Branches > origin/kotlin-experiments > Checkout as new branch'. Name the new branch something like kotlin-experiments-my-plugin. -[[create-the-plugin-metadata]] -== Create the plugin metadata +## Create the plugin metadata Apollo's plugins are stored in */game/plugin*, and each plugin has its own directory. Create one for your plugin - something like 'myplugin'. @@ -35,12 +32,12 @@ Inside that, create a directory called 'src', then right click it and Inside your plugin's directory (*not* in src) you'll want a *build.gradle* file, containing something like: -.... +```groovy plugin { name = "myplugin" authors = [ "your name" ] } -.... +``` Sometimes you need to use code from another plugin, which can be done @@ -48,8 +45,7 @@ like so: `dependencies = [ "util:lookup" ]` This imports the `lookup` plugin from `util`. -[[write-the-plugin]] -== Write the plugin +## Write the plugin Plugins are written in kotlin script (_.kts_), which is then transpiled into Java (bytecode) at compile time. Kotlin script is designed to be @@ -62,8 +58,7 @@ Apollo uses the _.plugin.kts_ extension to mark files as plugin scripts. Add a file named 'myplugin.plugin.kts' inside `src` and add the following code: -[source,kotlin] ----- +```kotlin import org.apollo.game.action.Action import org.apollo.game.message.impl.InventoryItemMessage import org.apollo.game.model.Item @@ -103,7 +98,7 @@ on { InventoryItemMessage::class } player.startAction(DropItemAction(player, slot)) terminate() } ----- +``` Here we have an *action*, and a *listener*, the two core features of plugins. diff --git a/docs/guide/plugins/03-testing-a-plugin.md b/docs/guide/plugins/03-testing-a-plugin.md new file mode 100644 index 000000000..e69de29bb diff --git a/docs/guide/plugins/04-sharing-plugin-code.md b/docs/guide/plugins/04-sharing-plugin-code.md new file mode 100644 index 000000000..e69de29bb diff --git a/docs/guide/toc.yml b/docs/guide/toc.yml new file mode 100644 index 000000000..e9431877a --- /dev/null +++ b/docs/guide/toc.yml @@ -0,0 +1,24 @@ +- name: Introduction + items: + - name: What is Apollo? + href: introduction/01-what-is-apollo.md +- name: Getting Started + items: + - name: Setting up a development environment + href: getting-started/01-setting-up-environment.md + + - name: Running the server + href: getting-started/02-running-apollo.md +- name: Plugins + items: + - name: What is a plugin? + href: plugins/01-what-is-a-plugin.md + + - name: Creating a plugin + href: plugins/02-creating-a-plugin.md + + - name: Testing plugins + href: plugins/03-testing-a-plugin.md + + - name: Sharing code with other plugins + href: plugins/04-sharing-plugin-code.md \ No newline at end of file diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 000000000..95887de53 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,4 @@ +# This is the **HOMEPAGE**. +Refer to [Markdown](http://daringfireball.net/projects/markdown/) for how to write markdown files. +## Quick Start Notes: +1. Add images to the *images* folder if the file is referencing an image. diff --git a/docs/src/docs/asciidoc/basics/what-is-apollo.adoc b/docs/src/docs/asciidoc/basics/what-is-apollo.adoc deleted file mode 100644 index 0100c6d0a..000000000 --- a/docs/src/docs/asciidoc/basics/what-is-apollo.adoc +++ /dev/null @@ -1,10 +0,0 @@ -= What is Apollo? - -Apollo is a high-performance, modular RuneScape emulator with a collection of utilities for managing data files and plugins. -Apollo targets revision 377 of the RuneScape client from late 2006. -It aims to achieve parity with the game server of that time and preserve the history of the game in doing so. - -== Is Apollo free? - -Apollo is open source and made available under the ISC license. -The git repository for the project is hosted under the https://github.com/apollo-rsps[Apollo RSPS organization] on GitHub. diff --git a/docs/src/docs/asciidoc/getting-started/running-apollo.adoc b/docs/src/docs/asciidoc/getting-started/running-apollo.adoc deleted file mode 100644 index cd7b9f5f4..000000000 --- a/docs/src/docs/asciidoc/getting-started/running-apollo.adoc +++ /dev/null @@ -1,63 +0,0 @@ -= Running Apollo - -This is a short guide to getting a copy of Apollo from our VCS and running a server able to accept connections from a game client. -It assumes you're starting fresh and have no local copy of Apollo. - -== Requirements - -You should be familiar with running programs on the UNIX shell or Windows command prompt. -There is also a short list of prerequisites below needed to complete this guide. - - * Git - * Gradle - * Java 8 - * RuneScape r377 game data files footnote:[We are unable to provide user-end assets like the game data or client due to copyright restrictions.] - -== Getting Apollo - -NOTE: Apollo is still in a development phase and has no current stable release, -so to run the server we need to build it from sources first. - -The URL for the Apollo git repository is https://github.com/apollo-rsps/apollo.git. You can clone this using the `git` command-line client -or by using the https://help.github.com/desktop/guides/contributing-to-projects/cloning-a-repository-from-github-desktop/[GitHub desktop client]. - -``` -> $ git clone https://github.com/apollo-rsps/apollo.git -``` - -If using the command line client, the repository will now be under a folder named _apollo_ and is ready to build. -When complete open a shell or Windows command prompt in that directory and move to the next step. - -== Building Apollo - -Apollo uses Gradle build scripts as it's build system. To build it, create a command prompt or shell in the Apollo repository folder and run: -``` -> $ gradle build genRsa -``` - -This will build the core server with the content plugins and run their respective tests. -This process takes around a minute to complete and when done will generate and output a set of RSA key parameters used by connecting clients to encrypt their credentials. -Save these for later. - -== Starting Apollo - -The last dependency is putting the game data in a location where the server can find it. -By default Apollo looks under `data/fs` in the root directory for a folder matching the release number. -Apollo supports release 377, so in our case we want the directory structure to look like this: - -``` -data/fs -└── 377 - ├── jingle1.mid - ├── main_file_cache.dat - ├── main_file_cache.idx0 - ├── main_file_cache.idx1 - ├── main_file_cache.idx2 - ├── main_file_cache.idxN -``` - -Now that everything is in place we can use the Gradle task to boot the server -``` -> $ gradle server:run -``` -After booting Apollo will have loaded the game data and be ready to accept connections. \ No newline at end of file diff --git a/docs/src/docs/asciidoc/index.adoc b/docs/src/docs/asciidoc/index.adoc deleted file mode 100644 index 12c7154b9..000000000 --- a/docs/src/docs/asciidoc/index.adoc +++ /dev/null @@ -1,26 +0,0 @@ -= Apollo Documentation -ifdef::env-github,env-browser[:outfilesuffix: .adoc] - -This is the home of Apollo's documentation. -Below you will find links to tutorial guides on running and using Apollo. - -== The Basics - -* <> - -== Getting Started - -* <> -* <> - -== Authoring plugins for Apollo - -* <> -* <> -* <> -* <> - -== References and Developer Resources - -* Apollo API Documentation[TODO] -* Plugin API Documentation[TODO] diff --git a/docs/toc.yml b/docs/toc.yml new file mode 100644 index 000000000..a429a7869 --- /dev/null +++ b/docs/toc.yml @@ -0,0 +1,6 @@ +- name: Guide + href: guide/ + +- name: Api Documentation + href: api/ + homepage: api/index.md