Add DocFX site generator skeleton

2026-07-04 16:49:11 +00:00 · 2019-07-17 23:17:12 +01:00
parent a090181ea3
commit fe457d762a
18 changed files with 250 additions and 114 deletions
@@ -0,0 +1,7 @@
+# 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.
@@ -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
+<https://github.com/apollo-rsps/apollo.git>. 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 <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:
+
+```
+> $ ./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.
@@ -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.
@@ -0,0 +1 @@
+# What is a plugin?
@@ -0,0 +1,131 @@
+# Creating a plugin
+
+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.
+
+Note: This tutorial is for developing Plugins for the kotlin-experiments
+branch prior to the release of the Kotlin plugin system for Apollo.
+
+## Create a working environment
+
+The project maintainers strongly recommend
+[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
+*import using gradle* on the next interface.
+
+Next, checkout the kotlin-experiments branch. To do this via IntelliJ,
+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
+
+Apollo's plugins are stored in */game/plugin*, and each plugin has its
+own directory. Create one for your plugin - something like 'myplugin'.
+
+Inside that, create a directory called 'src', then right click it and
+'Mark Directory as > Sources Root'. It should turn blue. +
+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
+like so: `dependencies = [ "util:lookup" ]`
+
+This imports the `lookup` plugin from `util`.
+
+## 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
+executed like a scripting language: you do *not* need a main function (a
+kotlin script consisting of nothing more than `println("Hello, world!")`
+will indeed compile and print "Hello, world!").
+
+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:
+
+```kotlin
+import org.apollo.game.action.Action
+import org.apollo.game.message.impl.InventoryItemMessage
+import org.apollo.game.model.Item
+import org.apollo.game.model.entity.Entity
+import org.apollo.game.model.entity.EntityType
+import org.apollo.game.model.entity.GroundItem
+import org.apollo.game.model.entity.Player
+
+class DropItemAction(val player: Player, val slot: Int): Action<Player>(delay = 0, immediate = true, player) {
+
+    override fun execute() {
+        val region = player.world.regionRepository.fromPosition(player.position)
+
+        if (region.getEntities<Entity>(player.position, EntityType.DYNAMIC_OBJECT, EntityType.STATIC_OBJECT).isEmpty()) {
+            val amount = player.inventory.reset(slot)?.amount
+            if (amount == null) {
+                return
+            }
+
+            val item = GroundItem.create(player.world, player.position, Item(item, amount), player)
+            player.world.spawn(item)
+        } else {
+            player.sendMessage("You cannot drop this here.")
+        }
+
+        stop()
+    }
+
+}
+
+val DROP_OPTION_ID = 5
+val INVENTORY_INTERFACE_ID = 3214
+
+on { InventoryItemMessage::class }
+    .where { option == DROP_OPTION_ID && interfaceId == INVENTORY_INTERFACE_ID }
+    .then { player ->
+        player.startAction(DropItemAction(player, slot))
+        terminate()
+    }
+```
+
+Here we have an *action*, and a *listener*, the two core features of
+plugins.
+
+The `on {...}` lambda at the end is the listener, and listens for
+specific event types (typically a *Message* subclass) Here we are
+listening to `InventoryItemMessage`s, which are called whenever a player
+performs an action on an item in an inventory. +
+The `where` clause is used to filter out requests that don't match what
+we're looking for: here, we only care about messages where the player
+selected the fifth option (used for dropping), and when they selected
+that option on an item in the inventory (i.e. the interfaceId matches
+the inventory interface id). `where` is executed from the context of the
+intercepted message, so `option` and `interfaceId` are actually fields
+inside `InventoryItemMessage`. +
+The 'then' clause is executed if the `where` lambda evaluates to `true`.
+
+*Actions* are used to schedule player (or NPC)-related code to be
+executed in the future (and optionally, periodically). Plugins also have
+actions that can be used to suspend/asynchronously execute code. Here
+we're creating an `Action` that removes an item from the player's
+inventory and spawns a `GroundItem`. Because `Action`s are scheduled,
+`execute()` will be called every server pulse (tick), until the `stop()`
+function is called.
+
+Now you can build it by running `gradle build` in the command line, or
+in IntelliJ via 'View > Tool Windows > Gradle > Execute Gradle Task'
+(type 'build' for the command).
+
+Voila!
@@ -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