Re-wrap markdown files

Signed-off-by: Graham <gpe@openrs2.org>

CONTRIBUTING.md

@@ -3,16 +3,16 @@
 ## Introduction
 
 OpenRS2 is still in the early stages of development. The current focus is on
-building underlying infrastructure, such as the deobfuscator, rather than
+building underlying infrastructure, such as the deobfuscator, rather than game
-game content. This approach will make it much quicker to build game content in
+content. This approach will make it much quicker to build game content in the
-the long run, but it does mean OpenRS2 won't be particularly useful in the short
+long run, but it does mean OpenRS2 won't be particularly useful in the short
 term.
 
-If you're interested in contributing new features, you should discuss your
+If you're interested in contributing new features, you should discuss your plans
-plans in our [Discord][discord] server first. I have rough plans in my head for
+in our [Discord][discord] server first. I have rough plans in my head for the
-the future development direction. Communicating beforehand will avoid the need
+future development direction. Communicating beforehand will avoid the need for
-for significant changes to be made at the code review stage and make it less
+significant changes to be made at the code review stage and make it less likely
-likely for your contribution to be dropped entirely.
+for your contribution to be dropped entirely.
 
 ## Code style
 
@@ -43,8 +43,8 @@ commit history is tidy.
 OpenRS2 uses version 1.1 of the [Developer Certificate of Origin][dco] (DCO) to
 certify that contributors agree to license their code under OpenRS2's license
 (see the License section below). To confirm that a contribution meets the
-requirements of the DCO, a `Signed-off-by:` line must be added to the Git
+requirements of the DCO, a `Signed-off-by:` line must be added to the Git commit
-commit message by passing `--signoff` to the `git commit` invocation.
+message by passing `--signoff` to the `git commit` invocation.
 
 If you intend to make a large number of contributions, run the following
 commands from the repository root to add `Signed-off-by:` line to all your

README.md

@@ -4,9 +4,9 @@
 
 ## Introduction
 
-OpenRS2 is an open-source multiplayer game server and suite of associated
+OpenRS2 is an open-source multiplayer game server and suite of associated tools.
-tools. It is compatible with build 550 of the RuneScape client, which was
+It is compatible with build 550 of the RuneScape client, which was released in
-released in late 2009.
+late 2009.
 
 ## Prerequisites
 
@@ -20,8 +20,8 @@ on JDK-only tools, such as `jarsigner`, at runtime.
 OpenRS2 requires the original RuneScape client code, data and location file
 encryption keys, which we cannot legally distribute.
 
-These files must be manually placed in the `nonfree` directory (directly
+These files must be manually placed in the `nonfree` directory (directly beneath
-beneath the root of the repository), in the following structure:
+the root of the repository), in the following structure:
 
 ```
 nonfree
@@ -69,9 +69,9 @@ File -> Settings -> Build, Execution and Deployment -> Compiler. See
 
 ## License
 
-OpenRS2 is available under the terms of the [ISC license][isc], which is
+OpenRS2 is available under the terms of the [ISC license][isc], which is similar
-similar to the 2-clause BSD license. The full copyright notice and terms are
+to the 2-clause BSD license. The full copyright notice and terms are available
-available in the `LICENSE` file.
+in the `LICENSE` file.
 
 [discord-badge]: https://img.shields.io/discord/684495254145335298
 [discord]: https://chat.openrs2.org/

share/doc/client-parameters.md

@@ -63,8 +63,8 @@ applet. All other parameters are optional.
 | 0  | RuneScape              | `game0`           |
 | 1  | MechScape/Stellar Dawn | `game1`           |
 
-At the time 550 was released, MechScape used the same engine as RuneScape.
+At the time 550 was released, MechScape used the same engine as RuneScape. While
-While changing the parameter affects the client in a small number of ways, the
+changing the parameter affects the client in a small number of ways, the
 majority of differences between the two games is in the cache.
 
 When `game1` is used, the following changes are made in the client:

share/doc/cryptography.md

@@ -6,13 +6,13 @@
 combining its output with addition/subtraction, the client uses it as a stream
 cipher to encrypt the opcodes of packets.
 
-It was implemented to break packet injection bots, such as AutoRune. While
+It was implemented to break packet injection bots, such as AutoRune. While using
-using ISAAC in this manner only provides confidentiality, and not authenticity
+ISAAC in this manner only provides confidentiality, and not authenticity or
-or integrity, if the opcodes are tampered with the packet lengths will no
+integrity, if the opcodes are tampered with the packet lengths will no longer be
-longer be in sync between the client and server. This causes one or both of the
+in sync between the client and server. This causes one or both of the endpoints
-endpoints to read garbage opcodes, though the garbage opcodes may happen to
+to read garbage opcodes, though the garbage opcodes may happen to match valid
-match valid packets for a while. Eventually, one or both endpoints will detect
+packets for a while. Eventually, one or both endpoints will detect an invalid
-an invalid packet and close the connection.
+packet and close the connection.
 
 ## RSA
 
@@ -26,8 +26,8 @@ cache, ensuring that Jagex's code-signed applet could not be used to run
 arbitrary native code if an attacker tampers with the JS5 connection. This
 change was probably required by Jagex's certificate authority.
 
-Jagex used a 512-bit RSA key when build 550 was released, and due to the size
+Jagex used a 512-bit RSA key when build 550 was released, and due to the size of
-of the output buffer in the client, the maximum key size is 1,008 bits. Both of
+the output buffer in the client, the maximum key size is 1,008 bits. Both of
 these sizes are considered insecure by modern standards, and Jagex's 512-bit
 private key was factored in 2016.
 
@@ -61,8 +61,8 @@ directly by Jagex's 512-bit RSA key.
 
 ## Whirlpool
 
-[Whirlpool][whirlpool] is a cryptographic hash function. It is not used in
+[Whirlpool][whirlpool] is a cryptographic hash function. It is not used in build
-build 550, however, it is included here for completeness as it is supported by
+550, however, it is included here for completeness as it is supported by
 OpenRS2's cache library. It is used to verify the integrity of native libraries
 stored in the cache.
 

share/doc/faq.md

@@ -24,11 +24,11 @@ There are a mixture of reasons:
 
 * Availability of the original native libraries. I struggled to find the
   original native libraries for 550, except for 32-bit Windows. While Linux and
-  macOS natives are available for nearby revisions, they are not compatible
+  macOS natives are available for nearby revisions, they are not compatible with
-  with the 550 client.
+  the 550 client.
-* The original native libraries were not built for 64-bit Linux and macOS.
+* The original native libraries were not built for 64-bit Linux and macOS. While
-  While this was probably not a major problem in 2009, 64-bit architectures are
+  this was probably not a major problem in 2009, 64-bit architectures are now
-  now the norm.
+  the norm.
 * Non-x86 architectures like ARM and RISC-V are becoming more popular. If we
   start seeing a shift away from x86 on desktop machines, the native libraries
   will need to be built for those architectures.
@@ -38,9 +38,9 @@ There are a mixture of reasons:
 * I anticipate that at some point in the future the Linux AWT implementation
   will be ported from X11 to Wayland, which will require porting the jaggl
   native library from GLX to EGL.
-* The switch away from OpenGL to newer graphics APIs like Metal and Vulkan
+* The switch away from OpenGL to newer graphics APIs like Metal and Vulkan might
-  might eventually necessitate the inclusion of OpenGL to Metal/Vulkan
+  eventually necessitate the inclusion of OpenGL to Metal/Vulkan translation
-  translation layers.
+  layers.
 * I'm concerned about backwards compatibility and bit rot. The original native
   libraries were compiled 10 years ago, and at some point one of their
   dependencies might drop backwards binary compatibility.
@@ -50,8 +50,7 @@ There are a mixture of reasons:
 Even though OpenRS2 does not distribute Jagex's intellectual property, there is
 a risk that it could be taken down from a service like GitHub by mistake,
 causing disruption. Running our own infrastructure allows us to keep backups of
-data not held in the Git repository, such as issues. If necessary, we can
+data not held in the Git repository, such as issues. If necessary, we can switch
-switch to a different hosting provider at short notice while retaining such
+to a different hosting provider at short notice while retaining such data.
-data.
 
 [nar-maven-plugin]: https://maven-nar.github.io/

share/doc/protocol/login.md

@@ -20,10 +20,10 @@ packets in a loop, rather than only permitting a single login packet to be sent
 during the handshake process, which is how most current private servers are
 currently implemented.
 
-For example, it is possible to send an `INIT_GAME_CONNECTION` packet followed
+For example, it is possible to send an `INIT_GAME_CONNECTION` packet followed by
-by an `INIT_JS5REMOTE_CONNECTION` packet. The connection will successfully
+an `INIT_JS5REMOTE_CONNECTION` packet. The connection will successfully switch
-switch to JS5 mode, even though this is not the normal sequence of packets sent
+to JS5 mode, even though this is not the normal sequence of packets sent by the
-by the client.
+client.
 
 ### 14 (`INIT_GAME_CONNECTION`)
 
@@ -68,9 +68,9 @@ hash to load balance between login servers, but this has not been confirmed.
 | Byte\[n\]     | RSA-encrypted payload                        |
 
 The unknown byte hard-coded to `0` in a client script might represent the
-language. It is consistent with the ID for English. We can infer that there
+language. It is consistent with the ID for English. We can infer that there were
-were language-specific versions of the cache, as the surviving copy does not
+language-specific versions of the cache, as the surviving copy does not contain
-contain translations.
+translations.
 
 The structure of the plaintext payload is described below:
 
@@ -255,8 +255,8 @@ your Message Centre for details.
 
 ### 5 (`DUPLICATE`)
 
-**Message:** Your account has not logged out from its last session. Try again
+**Message:** Your account has not logged out from its last session. Try again in
-in a few minutes.
+a few minutes.
 
 ### 6 (`CLIENT_OUT_OF_DATE`)
 
@@ -294,29 +294,30 @@ subscribe or use a different world.
 
 ### 14 (`UPDATE_IN_PROGRESS`)
 
-**Message:** The server is being updated. Please wait a few minutes and try again.
+**Message:** The server is being updated. Please wait a few minutes and try
+again.
 
 ### 15 (`RECONNECT_OK`)
 
 ### 16 (`TOO_MANY_ATTEMPTS`)
 
-**Message:** Too many incorrect logins from your address. Please wait 5 minutes before
+**Message:** Too many incorrect logins from your address. Please wait 5 minutes
-trying again.
+before trying again.
 
 ### 17 (Account in members-only area)
 
-**Message:** You are standing in a members-only area. To play on this world, move to a free
+**Message:** You are standing in a members-only area. To play on this world,
-area first.
+move to a free area first.
 
 ### 18 (`LOCKED`)
 
-**Message:** Your account has been locked as we suspect it has been stolen. Click here to
+**Message:** Your account has been locked as we suspect it has been stolen.
-recover your account.
+Click here to recover your account.
 
 ### 19 (Fullscreen is members-only)
 
-**Message:** Fullscreen is currently a members-only feature. To log in, either return to the
+**Message:** Fullscreen is currently a members-only feature. To log in, either
-main menu and exit fullscreen or use a members' account.
+return to the main menu and exit fullscreen or use a members' account.
 
 ### 20 (Invalid login server requested)
 
@@ -328,8 +329,8 @@ main menu and exit fullscreen or use a members' account.
 |--------------|-------------------------|
 | UnsignedByte | Hop time                |
 
-**Message:** You have only just left another world. Your profile will be transferred in <n>
+**Message:** You have only just left another world. Your profile will be
-seconds.
+transferred in <n> seconds.
 
 The number of remaining seconds is calculated using the following formula:
 (hopTime * 60 + 180) / 50
@@ -348,11 +349,13 @@ The number of remaining seconds is calculated using the following formula:
 
 ### 25 (`UNKNOWN_REPLY_FROM_LOGINSERVER`)
 
-**Message:** Unexpected loginserver response. Please try using a different world.
+**Message:** Unexpected loginserver response. Please try using a different
+world.
 
 ### 26 (`IP_BLOCKED`)
 
-**Message:** This comptuer's address has been blocked as it was used to break our rules.
+**Message:** This comptuer's address has been blocked as it was used to break
+our rules.
 
 ### 27 (Service unavailable)
 

share/doc/protocol/overview.md

@@ -3,14 +3,14 @@
 The RuneScape protocol runs on top of the [Transmission Control Protocol
 (TCP)][tcp]. As TCP is stream-oriented, a framing scheme is required to
 determine where one packet ends and where the next begins. RuneScape primarily
-uses a [type-length-value (TLV)][tlv] scheme for framing, though some
+uses a [type-length-value (TLV)][tlv] scheme for framing, though some exceptions
-exceptions do exist - for example, the JAGGRAB and JS5 protocols use different
+do exist - for example, the JAGGRAB and JS5 protocols use different framing
-framing schemes.
+schemes.
 
 A RuneScape connection may be in several states, each of which has a different
 set of opcodes (types in TLV parlance). Opcodes may have different meanings in
-different states. Opcodes may be optionally encrypted with the [ISAAC stream
+different states. Opcodes may be optionally encrypted with
-cipher][isaac].
+the [ISAAC stream cipher][isaac].
 
 All connections start in the [login](login.md) state.
 
@@ -52,13 +52,13 @@ They are structured as follows:
 ## Opcode encryption
 
 Opcodes are encrypted by adding the opcode to the next 32-bit output from the
-ISAAC random number generator and truncating the result to 8 bits. Decryption
+ISAAC random number generator and truncating the result to 8 bits. Decryption is
-is the same  process in reverse: the 32-bit output is subtracted from the
+the same process in reverse: the 32-bit output is subtracted from the encrypted
-encrypted opcode, and then the result is truncated to 8 bits.
+opcode, and then the result is truncated to 8 bits.
 
 There are two ISAAC random number generators: one used for upstream (client ->
-server) traffic and one used for downstream (server -> client) traffic. Both
+server) traffic and one used for downstream (server -> client) traffic. Both are
-are initialised with a seed consisting of four 32-bit integers.
+initialised with a seed consisting of four 32-bit integers.
 
 The upstream seed is the same as the downstream seed, except each integer
 component is incremented by 50.

share/doc/reference-counting.md

@@ -1,7 +1,7 @@
 # Reference counting
 
-[Netty][netty] uses reference counting for some objects, such as `ByteBuf`s.
+[Netty][netty] uses reference counting for some objects, such as `ByteBuf`s. The
-The Netty documentation explains its
+Netty documentation explains its
 [use of reference counting][netty-ref-counting] in more detail.
 
 OpenRS2 has an extension method that automatically wraps a block of code in a
@@ -39,9 +39,9 @@ alloc.buffer().use { buf ->
 
 If any of the code prior to the `return` fails, the buffer is released.
 
-If the `return` is reached, no more exceptions can occur. The reference count
+If the `return` is reached, no more exceptions can occur. The reference count is
-is increased to counteract the `finally` block decreasing it, such that by the
+increased to counteract the `finally` block decreasing it, such that by the time
-time the buffer reaches the caller its reference count is 1.
+the buffer reaches the caller its reference count is 1.
 
 [netty]: https://netty.io/
 [netty-ref-counting]: https://netty.io/wiki/reference-counted-objects.html