diff --git a/README.md b/docs/README.md similarity index 100% rename from README.md rename to docs/README.md diff --git a/docs/wiki/Extensions.md b/docs/wiki/Extensions.md new file mode 100644 index 0000000..5946e88 --- /dev/null +++ b/docs/wiki/Extensions.md @@ -0,0 +1,248 @@ +# Warning - this wiki page is outdated - will be updated soon. In the meanwhile, ask any questions in the Discord server or check the [template extensions](https://github.com/sirjonasxx/G-Earth-template-extensions) + +G-Earth supports console & GUI extensions, this page is focused on extension structure and development. + +Visit https://github.com/sirjonasxx/G-Earth-template-extensions to start from a minimalistic template extension + +## Features +* Packet hash/name support +* Interception of incoming/outgoing packets +* Full chat console support for I/O + +## Console extensions + +Console extensions are the most basic kind of extensions, a few lines of code can get us started. +A console extension is made of a Java class that extends _Extension_. + +Let's start a sample extension creating a maven project: + +Since G-Earth is built using maven, once we've compiled G-Earth, it's possible to add it as a project dependency: +```xml + + + 4.0.0 + + G-EarthGang + SampleExtension + 1.0-SNAPSHOT + + + + org.apache.maven.plugins + maven-jar-plugin + 2.5 + + ${project.build.directory}/bin + + + true + true + lib/ + SampleExtension + false + + + + + + maven-assembly-plugin + 2.5 + + + package + + single + + + + + ${project.build.directory}/bin + + + SampleExtension + + + + jar-with-dependencies + + SampleExtension + false + + + + org.apache.maven.plugins + maven-compiler-plugin + + 8 + 8 + + + + + + + + G-Earth + G-Earth + 0.2 + + + +``` + +That should be enough to configure maven. Now let's move on to the code. + +Every extension needs to include an _ExtensionInfo_ annotation in order to identify the extension, our ExtensionInfo would look like this: +```java +@ExtensionInfo( + Title = "Sample Extension", + Description = "Used for the wiki", + Version = "1.0", + Author = "G-Earth" +) +``` + +The extension constitutes a standalone jar, so we'll need to include a main method to start it up like this: +```java +public class SampleExtension extends Extension { + private SampleExtension(String[] args) { + super(args); + } + + public static void main(String[] args) { + new SampleExtension(args).run(); + } +} +``` + +That would be a bare minimum to get it loaded into G-Earth, now let's have a look at the API to improve our little extension + +## A quick look to the extensions API + +**!!!Warning: since G-Earth 1.4, HashSupport has been renamed to PacketInfoSupport!!!** + +In this section we'll build upon the previous example with the functionality provided by G-Earth's API + +### Initializing our extension + +_initExtension_ is called whenever G-Earth loads the extension, it's specially useful to init the _HashSupport_ and other features, we'll use it in the following examples + + +### Intercepting packets +The _intercept_ method lets us intercept a packet from its id and modify it if we want to. Typically, we use this function call inside _initExtension_. +```java +intercept(HMessage.Side.TOCLIENT, 4000, hMessage -> { + // oops we got disconnected +}); +``` + +### Sending packets +G-Earth includes the sendTo[Client/Server] method in order to send packets. + +```java +sendToClient(new HPacket("{l}{u:1234}")); +// or +sendToClient(new HPacket(1234)); +``` + +### Doing stuff upon client connection + +```java +@Override +protected void onStartConnection() { + // we're connected to habbo +} +``` + +### Minimalistic interaction; onClick + +If (and only if) the _onClick_ method is overridden by your extension, G-Earth will display a green "Start" button next to your extension and the function will get called on-click. For form extensions, this option is automatically used to open the GUI. For non-gui extensions, this is an additional feature you could use. + +```java +@Override +protected void onClick() { + // the user clicked this extension! I must do something relevant here +} +``` + + +### HashSupport + +_HashSupport_ allows us to use hashes/names in order to intercept and send packets, using the aforementioned methods. + +```java +private HashSupport mHashSupport; +@Override +protected void initExtension() { + // This is called when G-Earth loads the extension + mHashSupport = new HashSupport(this); + + mHashSupport.intercept(HMessage.Side.TOCLIENT, "RoomUserStartTyping", hMessage -> { + mHashSupport.sendToServer("RoomUserStopTyping"); + }); +} +``` + +### ChatConsole +_ChatConsole_ is a new G-Earth feature that allows us to use the in-game chat in order to easily communicate with the extension, it can read your input and write messages, you can also set a welcome message, we'll add it to our example. +(side note: the implementation of ChatConsole hides the whole thing from the Habbo servers, so all interaction stays local) + +```java +private HashSupport mHashSupport; +private ChatConsole mChatConsole; +@Override +protected void initExtension() { + // This is called when G-Earth loads the extension + mHashSupport = new HashSupport(this); + mChatConsole = new ChatConsole(mHashSupport, this, "I'm a welcome message!"); + + mChatConsole.onInput(input -> { + if (input.equals("ping")) + mChatConsole.writeOutput("pong", false); + }); +} +``` + +Once loaded it will appear to your friend's list
+![](https://i.imgur.com/XqYFZmT.png) + +It will show the welcome message after typing _:info_
+![](https://i.imgur.com/1mfBxYm.png)
+![](https://i.imgur.com/294PNUE.png) + +If used correctly it can be pretty powerful. + +## GUI extensions + +We'll build a simple GUI based extension using the concepts we learnt on the console extension part. + +The main difference is that instead of extending from _Extension_ we'll extend from _ExtensionForm_. This introduces some changes, for example, in order to call to our extension in _main_, we'll call _runExtensionForm_ instead of the constructor. + +```java +public class SampleExtension extends ExtensionForm { + public static void main(String[] args) { + runExtensionForm(args, SampleExtension.class); + } +} +``` + +Since _ExtensionForm_ is an abstract class, we'll have to implement _launchForm_ in order to setup the javafx components +```java +public ExtensionForm launchForm(Stage primaryStage) throws Exception { + FXMLLoader loader = new FXMLLoader(getClass().getResource("sampleextension.fxml")); + Parent root = loader.load(); + + primaryStage.setTitle("Sample extension"); + primaryStage.setScene(new Scene(root)); + primaryStage.setResizable(false); + + return loader.getController(); +} +``` + +Assuming you've created the .fxml file, this code would be enough for G-Earth to load your extension. + + +From there, you can design your own UI and use the API to create a fully functional extension. \ No newline at end of file diff --git a/docs/wiki/G-Python-qtConsole.md b/docs/wiki/G-Python-qtConsole.md new file mode 100644 index 0000000..5b45154 --- /dev/null +++ b/docs/wiki/G-Python-qtConsole.md @@ -0,0 +1,58 @@ +## Requirements +* Understand the G-Python extension interface (https://github.com/sirjonasxx/G-Python) +* Make sure your python version (`python --version` on commandline) is >= 3.2 +* Execute the following line on commandline: `python -m pip install qtconsole pyqt5 jupyter-console g-python` to install the required packages + +(IMPORTANT: On Linux devices, the installation command might require a `sudo`, since G-Earth runs in `sudo` as well.) + +## Usage +1. Go to the "Extra" tab on G-Earth and check the "Enable G-Python Scripting" checkbox +2. Go to the "Extensions" tab and open a G-Python shell + +The shell will automatically do the following things for you: +* Import all G-Python classes & modules (`Extension`, `Direction`, `HMessage`, `HPacket`, `hparsers`, `htools`) +* Import the `sleep()` function from the `time` module +* Initialize a G-Python extension (named `ext`) and connect it to G-Earth +* Create an interface for all methods of the Extension object (for example: `ext.send_to_server(packet)` can also be executed with just `send_to_server(packet)`) + +![G-Python shell extension](https://i.imgur.com/ekOPLYu.png) + +### QtConsole shortcuts + +Shortcuts: +* TAB -> Autocomplete +* SHIFT+TAB -> Show function arguments + docs +* ENTER -> Execute the entered python script or continue it on the next line, depending on context +* CTRL+ENTER -> Same as "ENTER", but always continue the current script +* SHIFT+ENTER -> Same as "ENTER", but always execute + +Commands: +* %quickref -> list of all qtConsole commands +* %clear -> clears the window +* %save -> saves specific lines to a file (example: `%save test 4-7`, saves lines 4 to 7 to `test.py`) +* %load -> loads script from a file (example: `load test`, loads `test.py`) + +## Example +#### Example 1: send all user signs + +![example 1](https://i.imgur.com/4kjnPlo.png) + +_(hint: to save this script: `%save all_signs 23-24`)_ + +#### Example 2: wave when typing "wave" + +![example 2](https://i.imgur.com/xo6GhOi.png) + +_(hint: if you're going to `sleep()` during an `intercept()` callback, do an asynchronous intercept (check g-python repo), or all incoming/outgoing packet flow will be paused)_ + +_(hint: in the method signature `def on_speech(message: HMessage)`, `: HMessage` isn't required but makes auto-completion easier)_ + +#### Example 3: get all room furniture + +![example 3](https://i.imgur.com/CJCErDh.png) + +#### Example 4: get all room users + +![example 4](https://i.imgur.com/b2czJUw.png) + +_(prints the list of all HEntities in the room, in which all of them are mapped to their corresponding string representation)_ \ No newline at end of file diff --git a/docs/wiki/Home.md b/docs/wiki/Home.md new file mode 100644 index 0000000..708dba2 --- /dev/null +++ b/docs/wiki/Home.md @@ -0,0 +1,9 @@ +Welcome to the G-Earth wiki! + +For extension development, go to https://github.com/sirjonasxx/G-Earth/wiki/Extensions + +For troubleshooting, go to https://github.com/sirjonasxx/G-Earth/wiki/Troubleshooting + +For Mac installation, go to https://github.com/sirjonasxx/G-Earth/wiki/macOs-Installation-guide + +For the G-Python console, go to https://github.com/sirjonasxx/G-Earth/wiki/G-Python-qtConsole \ No newline at end of file diff --git a/docs/wiki/Troubleshooting.md b/docs/wiki/Troubleshooting.md new file mode 100644 index 0000000..524c5b5 --- /dev/null +++ b/docs/wiki/Troubleshooting.md @@ -0,0 +1,38 @@ +**HABBO AIR CURRENTLY DOESN'T WORK FOR MAC** + +There are some known issues with the execution G-Earth, please read this through carefully. + +First of all, make sure you have extracted the .rar file into its own folder. +If you're using a mac; make sure you have completed the mac-installation wiki page. + +## Problem 1: G-Earth doesn't open +* It's recommended to use Java 8, some problems have occurred with people using Java 11 or other versions. It shouldn't be hard to fix this with a simple google search. +* On Linux, if you get a "Invalid MIT-MAGIC-COOKIE-1" exception, execute "xhost +local:" in a terminal +* On Linux, if you get a "could not find or load main class gearth.Main", javafx might not be installed. Execute "apt install openjfx" to install javafx +* It will almost always be an issue with Java, so try reinstalling + +## Problem 2: Stuck at 76% or 57% +* On windows; navigate to https://visualstudio.microsoft.com/downloads/ and download the c++ redistributable 2017 ( https://imgur.com/a/bgvL8fN ), make sure to select the right version. +* Try another browser. (on Mac, use Firefox. On Windows, use Chrome, Firefox or Opera, others might work as well, but IE and Edge do not) +* MAKE SURE your downloaded the right .rar file, for Windows, check if you're running on a 32bit or 64bit device first. +* If you got a message redirecting you to the troubleshooting page, the issue likely has to do with something G-Mem related. + - Try double clicking G-Mem.exe and see if any errors appear, this may help you in troubleshooting + - In rare cases, I found people that couldn't use G-Mem.exe if it was executed with admin permissions. If you can verify you have the same issue, you could make your hosts file editable by non-admin users and run G-Earth in a non-admin fashion. Beware: this is a security risk but I found no other solution + +## Problem 3: Habbo loads, but G-Earth isn't connected +* Your hosts file might have some permissions issues. Delete it and place a new one: https://github.com/sirjonasxx/G-Earth/issues/17 +* The port of the hotel you're trying to connect with (30000 or 38101 on most hotels) must not be in use by any other process than G-Earth. There are platform-specific ways to find out what ports are in-use by googling. +* Make sure you don't have a VPN(/browser extension) enabled +* Your antivirus might be the problem, try to disable it +* Your firewall might be the problem, try to disable it + +## Creating an Issue +If the solutions did NOT help you, navigate to https://github.com/sirjonasxx/G-Earth/issues and, if it hasn't been solved before, create a new issue. +Include the following things in your issue: +* Java version +* Your operating system +* For windows: open CMD as administrator and navigate to the G-Earth folder, execute "java -jar G-Earth.jar" and wait for your specific problem to occur. Afterwards, take a screenshot and include it in the issue. +* For mac&linux: the same thing, but open a terminal instead and use the command "sudo java -jar G-Earth.jar" + + +If you had an issue and solved it with a different solution and feel like it belongs on this page, feel free to create an issue. \ No newline at end of file diff --git a/docs/wiki/macOs-Installation-guide.md b/docs/wiki/macOs-Installation-guide.md new file mode 100644 index 0000000..a098176 --- /dev/null +++ b/docs/wiki/macOs-Installation-guide.md @@ -0,0 +1,24 @@ +**NOTE: Currently supported browsers: ONLY Firefox and Chromium, works on Habbo AIR too** + +In order to run G-Earth on macOs, you'll need to sign G-Mem (our memory searcher). This wiki page will cover that process. + +First we'll create a certificate in order to sign it: +1. Open the Keychain Access application (You may find it inside Utilities).£ +2. Select Certificate Assistant -> Create a Certificate.
+![](https://i.imgur.com/G6SS6ac.png) +3. Choose a name for the certificate (I'll use "gmem-cert") and set "Certificate Type" to "Code Signing". Also select "Let me override defaults" option.
+![](https://i.imgur.com/CAUI5Xi.png) +4. Click on "Continue" until "Specify a Location For The Certificate" appears, then set "Keychain" to "System".
+![](https://i.imgur.com/HwLDtmE.png) +5. Continue, the certificate will be created then.
+![](https://i.imgur.com/gYiKmZA.png) + +Once created, we are able to codesign gmem from Terminal
+`codesign -fs "gmem-cert" /G-Mem` + +![](https://i.imgur.com/xkryoJz.png) + +Now you're ready to open G-Earth from Terminal
+`sudo java -jar G-Earth.jar` + +If you experience any other issues and the troubleshooting page doesn't help, it might be useful to have a look at the following issues: [#67](../issues/67) [#10](../issues/10) \ No newline at end of file