# ywot-clean

A reconstructed version of `ywot-bot` built off of clean programming principles and a minimal but fast base API.

I'd love to hear about how you're using this api or any bugs you find. Please contact me at [hr@hrhr.dev](mailto:hr@hrhr.dev).

## Getting Started

To download and run this library, install node.js and npm, if you haven't already, and run:
```bash
git clone https://github.com/feynmansfedora/ywot-clean.git
cd ywot-clean
npm i
node examples/helloworld.js # To try out the hello world (read the code for more detail)
```

## Quirks

The server is a little bit weird sometimes. Most abstractions should work, but if you're trying to get into extending the code, be aware that:

- Each write only takes 200 characters
- Each server command MUST be separated by about a second or you will be kicked (I recommend `tools/queue.js` for handling this)
- On the backend, the server uses tiles to group data, but this has mostly been abstracted

## Features

Currently, `socket.js` provides `Socket` which has a few signals and functions (documented in the code, of course) which allow abstracted interfacing with YWOT. However, certain facilities available in the old version like queuing or fetch division were scrapped in favor of more direct limits due to the unmaintainability of the old style.

`space.js` provides some dense spatial data management with `Space`, which is really good for specific dialogs and tests, but constructs like `tools/search.js` are more useful for storing world updates.

`examples/helloworld.js` can get you started. Everything in the core API (`socket.js`, `space.js`) should be pretty stable, but please don't hesitate to report a bug.

## Directory Structure

Top-level scripts are part of the core API: `socket.js` and `space.js` are pretty portable and abstract a lot of the ugly parts of yourworldoftext (like 8x16 tiles).

Then, `examples/` provides use cases for it. `helloworld.js` is a basic "Hello World" printer, `spam.js` spams one message without attempting to conserve bandwidth, and `jarvis.js` provides the most advanced example (responds to the word `jarvis` by overwriting it with `yes, my liege`, but is capable of much more complex behavior).

`tools` and `utils` are similar to eachother in that they aren't very useful on their own, but are mostly distinct tools from the core API or user-facing scripts. The main difference is complexity: `tools` is reserved for complex (often persistent) utilities like `search` and `utils` for simple one-off functions like vector arithmetic, a min/max calculator for an array of coordinates, or helper tools for `space.comb`. They have been primarily motivated by attempts to discretize `examples`.

## Stability

- `space.js` and `socket.js` are not very liable to change, and probably don't have any big bugs.
- `tools` is a bit more volatile, and are non-trivial extensions to the core API, so they may break, but `search` and `queue` are decent.
- `utils` doesn't get overwritten/modified often, just extended, and the code is mostly "stub code," so relying on that is a pretty safe bet.
- `examples` are highly volatile and expected to break, so don't rely on them because they are user endpoints, but `helloworld.js` will probably be fine for a while.
- `tests` also likely won't change, but it's relatively simple and probably won't "break."