diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c10b8e39..092102f9 100644 --- a/CONTRIBUTING.md +++ b/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 -game content. This approach will make it much quicker to build game content in -the long run, but it does mean OpenRS2 won't be particularly useful in the short +building underlying infrastructure, such as the deobfuscator, rather than game +content. This approach will make it much quicker to build game content in the +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 -plans in our [Discord][discord] server first. I have rough plans in my head for -the future development direction. Communicating beforehand will avoid the need -for significant changes to be made at the code review stage and make it less -likely for your contribution to be dropped entirely. +If you're interested in contributing new features, you should discuss your plans +in our [Discord][discord] server first. I have rough plans in my head for the +future development direction. Communicating beforehand will avoid the need for +significant changes to be made at the code review stage and make it less likely +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 -commit message by passing `--signoff` to the `git commit` invocation. +requirements of the DCO, a `Signed-off-by:` line must be added to the Git commit +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 diff --git a/README.md b/README.md index 1091407d..8e8fb20e 100644 --- a/README.md +++ b/README.md @@ -4,9 +4,9 @@ ## Introduction -OpenRS2 is an open-source multiplayer game server and suite of associated -tools. It is compatible with build 550 of the RuneScape client, which was -released in late 2009. +OpenRS2 is an open-source multiplayer game server and suite of associated tools. +It is compatible with build 550 of the RuneScape client, which was released in +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 -beneath the root of the repository), in the following structure: +These files must be manually placed in the `nonfree` directory (directly beneath +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 -similar to the 2-clause BSD license. The full copyright notice and terms are -available in the `LICENSE` file. +OpenRS2 is available under the terms of the [ISC license][isc], which is similar +to the 2-clause BSD license. The full copyright notice and terms are available +in the `LICENSE` file. [discord-badge]: https://img.shields.io/discord/684495254145335298 [discord]: https://chat.openrs2.org/ diff --git a/share/doc/client-parameters.md b/share/doc/client-parameters.md index 52f858a1..0f17bc09 100644 --- a/share/doc/client-parameters.md +++ b/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. -While changing the parameter affects the client in a small number of ways, the +At the time 550 was released, MechScape used the same engine as RuneScape. While +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: diff --git a/share/doc/cryptography.md b/share/doc/cryptography.md index 389fdc60..0bbafa6c 100644 --- a/share/doc/cryptography.md +++ b/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 -using ISAAC in this manner only provides confidentiality, and not authenticity -or integrity, if the opcodes are tampered with the packet lengths will no -longer be in sync between the client and server. This causes one or both of the -endpoints to read garbage opcodes, though the garbage opcodes may happen to -match valid packets for a while. Eventually, one or both endpoints will detect -an invalid packet and close the connection. +It was implemented to break packet injection bots, such as AutoRune. While using +ISAAC in this manner only provides confidentiality, and not authenticity or +integrity, if the opcodes are tampered with the packet lengths will no longer be +in sync between the client and server. This causes one or both of the endpoints +to read garbage opcodes, though the garbage opcodes may happen to match valid +packets for a while. Eventually, one or both endpoints will detect an invalid +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 -of the output buffer in the client, the maximum key size is 1,008 bits. Both of +Jagex used a 512-bit RSA key when build 550 was released, and due to the size 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 -build 550, however, it is included here for completeness as it is supported by +[Whirlpool][whirlpool] is a cryptographic hash function. It is not used in build +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. diff --git a/share/doc/faq.md b/share/doc/faq.md index afd69e54..bc0161c8 100644 --- a/share/doc/faq.md +++ b/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 - with the 550 client. -* The original native libraries were not built for 64-bit Linux and macOS. - While this was probably not a major problem in 2009, 64-bit architectures are - now the norm. + macOS natives are available for nearby revisions, they are not compatible with + the 550 client. +* The original native libraries were not built for 64-bit Linux and macOS. While + this was probably not a major problem in 2009, 64-bit architectures are now + 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 - might eventually necessitate the inclusion of OpenGL to Metal/Vulkan - translation layers. +* The switch away from OpenGL to newer graphics APIs like Metal and Vulkan might + eventually necessitate the inclusion of OpenGL to Metal/Vulkan translation + 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 -switch to a different hosting provider at short notice while retaining such -data. +data not held in the Git repository, such as issues. If necessary, we can switch +to a different hosting provider at short notice while retaining such data. [nar-maven-plugin]: https://maven-nar.github.io/ diff --git a/share/doc/protocol/login.md b/share/doc/protocol/login.md index b5543553..c3811eb7 100644 --- a/share/doc/protocol/login.md +++ b/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 -by an `INIT_JS5REMOTE_CONNECTION` packet. The connection will successfully -switch to JS5 mode, even though this is not the normal sequence of packets sent -by the client. +For example, it is possible to send an `INIT_GAME_CONNECTION` packet followed by +an `INIT_JS5REMOTE_CONNECTION` packet. The connection will successfully switch +to JS5 mode, even though this is not the normal sequence of packets sent by the +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 -were language-specific versions of the cache, as the surviving copy does not -contain translations. +language. It is consistent with the ID for English. We can infer that there were +language-specific versions of the cache, as the surviving copy does not contain +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 -in a few minutes. +**Message:** Your account has not logged out from its last session. Try again in +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 -trying again. +**Message:** Too many incorrect logins from your address. Please wait 5 minutes +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 -area first. +**Message:** You are standing in a members-only area. To play on this world, +move to a free area first. ### 18 (`LOCKED`) -**Message:** Your account has been locked as we suspect it has been stolen. Click here to -recover your account. +**Message:** Your account has been locked as we suspect it has been stolen. +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 -main menu and exit fullscreen or use a members' account. +**Message:** Fullscreen is currently a members-only feature. To log in, either +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 -seconds. +**Message:** You have only just left another world. Your profile will be +transferred in 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) diff --git a/share/doc/protocol/overview.md b/share/doc/protocol/overview.md index 89a4b663..a8d068d8 100644 --- a/share/doc/protocol/overview.md +++ b/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 -exceptions do exist - for example, the JAGGRAB and JS5 protocols use different -framing schemes. +uses a [type-length-value (TLV)][tlv] scheme for framing, though some exceptions +do exist - for example, the JAGGRAB and JS5 protocols use different framing +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 -cipher][isaac]. +different states. Opcodes may be optionally encrypted with +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 -is the same process in reverse: the 32-bit output is subtracted from the -encrypted opcode, and then the result is truncated to 8 bits. +ISAAC random number generator and truncating the result to 8 bits. Decryption is +the same process in reverse: the 32-bit output is subtracted from the encrypted +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 -are initialised with a seed consisting of four 32-bit integers. +server) traffic and one used for downstream (server -> client) traffic. Both are +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. diff --git a/share/doc/reference-counting.md b/share/doc/reference-counting.md index f50aa262..2a8d431c 100644 --- a/share/doc/reference-counting.md +++ b/share/doc/reference-counting.md @@ -1,7 +1,7 @@ # Reference counting -[Netty][netty] uses reference counting for some objects, such as `ByteBuf`s. -The Netty documentation explains its +[Netty][netty] uses reference counting for some objects, such as `ByteBuf`s. The +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 -is increased to counteract the `finally` block decreasing it, such that by the -time the buffer reaches the caller its reference count is 1. +If the `return` is reached, no more exceptions can occur. The reference count is +increased to counteract the `finally` block decreasing it, such that by the time +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