Made adjustments to allow library to run in browser without Node. (#15)

Made adjustments to allow library to run in browser without Node
ThePhar · Jun 17, 2022 · e38d13d · e38d13d
1 parent 194d124
commit e38d13d
Show file tree

Hide file tree

Showing 8 changed files with 2,687 additions and 723 deletions.
diff --git a/.babelrc b/.babelrc
diff --git a/.github/workflows/npm-publish.yaml → .github/workflows/publish.yaml b/.github/workflows/npm-publish.yaml → .github/workflows/publish.yaml
diff --git a/README.md b/README.md
@@ -1,28 +1,25 @@
-# Archipelago.js
+# [Archipelago.JS](https://github.com/ThePhar/archipelago.js)
 ![GitHub](https://img.shields.io/github/license/thephar/archipelago.js?style=flat-square)
 ![GitHub Workflow Status](https://img.shields.io/github/workflow/status/thephar/archipelago.js/Lint%20and%20Build?style=flat-square)
 ![npm type definitions](https://img.shields.io/npm/types/archipelago.js?style=flat-square)
 ![npm](https://img.shields.io/npm/v/archipelago.js?style=flat-square)
 ![npm](https://img.shields.io/npm/dm/archipelago.js?style=flat-square)
 
-A general purpose library for communicating with Archipelago servers via Node.js.
+A general purpose library for communicating with Archipelago servers in Node.js or in the browser.
 
 **Note: This library is currently in active development and some key APIs may change between 0.x releases. __Use this
 library at your own risk.__**
 
 ## Getting Started
 
-Install `archipelago.js` into your npm project with the following command:
+### Node.js - JavaScript
 
-```bash
-npm install archipelago.js
-```
+Run `npm install archipelago.js` to add **Archipelago.JS** to your Node.js project.
 
 Here is an example client that connects and sends a hello message on connection. It also updates the console when a new
 message comes in.
 
 ```javascript
-// CommonJS Modules
 const { ArchipelagoClient, CommandPacketType, ItemsHandlingFlags } = require("archipelago.js");
 
 // Set up the AP client.
@@ -52,8 +49,91 @@ client.addListener("print", (packet) => {
 });
 ```
 
-The `ArchipelagoClient` handles all the main interactions with the Archipelago server, including sending and receiving 
-packets and maintaining the websocket connection.
+### TypeScript
+
+It's easy to also import **Archipelago.JS** into your TypeScript projects, as it contains full type definitions. Run 
+`npm install archipelago.js` to include it in your TypeScript file.
+
+Here's the same client example code as above, but note the ES-style import syntax.
+
+```typescript
+import { ArchipelagoClient, CommandPacketType, ItemsHandlingFlags } from "archipelago.js";
+
+// Set up the AP client.
+const client = new ArchipelagoClient("localhost:38281");
+const credentials = {
+    game: "Rogue Legacy",
+    name: "Phar",
+    uuid: "8da62081-7213-4543-97f6-b54d40e2fe52",
+    version: { major: 0, minor: 3, build: 2 },
+    items_handling: ItemsHandlingFlags.REMOTE_ALL,
+};
+
+// Connect to the Archipelago server.
+client
+    .connect(credentials)
+    .then(() => {
+        console.log(`Connected to room with ${client.data.players.size} players.`);
+
+        // Send a raw packet to the server!
+        client.send({ cmd: CommandPacketType.SAY, text: "Hello, everybody!" });
+    })
+    .catch(console.error);
+
+// Listen for packet events.
+client.addListener("print", (packet) => packet.text);
+
+```
+
+### In the Browser
+
+**Archipelago.JS** can also run in the browser using the WebSocket API. Download the `archipelago.min.js` file and
+include it with your web-based project. Then you can use it in your HTML/Javascript via the `archipealgoJS` global 
+variable.
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <title>Example</title>
+</head>
+<body>
+    <p>Open the console in your browser to see the output!</p>
+
+    <script src="archipelago.min.js"></script>
+    <script>
+        const { ArchipelagoClient, CommandPacketType, ItemsHandlingFlags } = archipelagoJS;
+
+        // Set up the AP client.
+        const client = new ArchipelagoClient("10.0.0.92:38281");
+        const credentials = {
+            game: "ChecksFinder",
+            name: "Phar",
+            uuid: "8da62081-7213-4543-97f6-b54d40e2fe52",
+            version: { major: 0, minor: 3, build: 2 },
+            items_handling: ItemsHandlingFlags.REMOTE_ALL,
+        };
+
+        // Connect to the Archipelago server.
+        client
+            .connect(credentials)
+            .then(() => {
+                console.log(`Connected to room with ${client.data.players.size} players.`);
+
+                // Send a raw packet to the server!
+                client.send({ cmd: CommandPacketType.SAY, text: "Hello, everybody!" });
+            })
+            .catch(console.error);
+
+        // Listen for packet events.
+        client.addListener("print", (packet) => packet.text);
+    </script>
+</body>
+</html>
+```
+
+## Some Helpful Manager Classes
 
 ### LocationsManager
 
@@ -101,10 +181,28 @@ console.log(client.players.name(1)); // Always their slot name.
 console.log(client.players.alias(2)); // Their current alias.
 ```
 
+## Contributing / Development
+
+To develop further or contribute to **Archipelago.JS** itself, just clone this repository to a desired location on your
+computer:
+
+```
+git clone https://github.com/ThePhar/archipelago.js && cd archipelago.js
+```
+
+Then run `npm install` to install all dependencies.
+
+**Archipelago.JS** is written in TypeScript and includes a string ESLint and Prettier config file to ensure code
+consistency. Be sure to follow the code standards and check your work with `npm run lint`. You can build your code by 
+running `npm run pack` (to package in a `.tgz` file) or `npm run build` (for a full `dist/` folder).
+
+It is recommended to work in a branch other than `main`, even if you fork, to avoid merge conflicts with GitHub when
+pull requests and squash merges happen.
+
 ## API Documentation & Other Links
 
-There is documentation in the GitHub pages section of this repository that includes all the available API. Please take
-a look for more information.
+The full API documentation is located [here](https://thephar.github.io/archipelago.js/). Please be sure to reference it, while
+you are developing your JavaScript-based clients.
 
 This library supports 100% of the Archipelago network protocol referenced [here](https://github.com/ArchipelagoMW/Archipelago/blob/main/docs/network%20protocol.md). See more information about 
 [Archipelago](https://archipelago.gg) at their website.