https://github.com/loathers/tome

Tome is a library written to support relay scripts for KoLMafia written in Typescript with React.
https://github.com/loathers/tome

Last synced: about 1 month ago
JSON representation

Tome is a library written to support relay scripts for KoLMafia written in Typescript with React.

• Host: GitHub
• URL: https://github.com/loathers/tome
• Owner: loathers
• Created: 2023-04-25T23:48:07.000Z (over 1 year ago)
• Default Branch: main
• Last Pushed: 2024-10-21T12:13:15.000Z (2 months ago)
• Last Synced: 2024-10-24T17:54:28.427Z (about 2 months ago)
• Language: TypeScript
• Size: 1.44 MB
• Stars: 0
• Watchers: 5
• Forks: 2
• Open Issues: 0
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

README

        
# Tome

Tome is a library written to support relay scripts for KoLmafia written in TypeScript with React.

It works as a drop-in replacement for the `kolmafia` typescript bindings, and allows use of `libram`.

Any `kolmafia` function call will return a placeholder value on the first call, and then silently

fetch the correct value in the background, triggering a UI refresh in React when that value arrives.

Essentially, `tome` goes for eventual UI consistency.

## Install

To get started, simply run:

```bash

yarn add kolmafia@npm:tome-kolmafia-mock@^$(npm view tome-kolmafia-mock version) tome-kolmafia-react tome-kolmafia-lib

```

Afterwards you'll be able to import functions as if from kolmafia, and even use

[libram](https://github.com/loathers/libram) in the browser!

The tome developers recommend using TypeScript and vite for your build system.

If VS Code is suggesting imports from `tome-kolmafia-lib/kolmafia` in addition to from `kolmafia`,

you can exclude this with the following snippet in `settings.json`:

```json

"typescript.preferences.autoImportSpecifierExcludeRegexes": [

  "^tome-kolmafia-lib/kolmafia$"

]

```

## Usage

After that, there's a little more work to be done before you can fully benefit. You'll need

to wrap your App on some level (above wherever you want to run libram/kolmafia functions) with a

`RefreshContextProvider`. Then the rest of your app should be in a subcomponent of that context

provider. A top-level component in your app needs to then call `useContext(RefreshContext)`.

By default, your app will refresh its data any time the main pane is navigated or whenever key

pieces of character state change.

## Framework

Typically, you will want to have some kind of a loader script that either creates its own relay

frame (for scripts like Guide or CHiT that take up a whole pane), or inserts a div into the KoL

HTML (for relay override scripts) that then can get filled by React or another UI framework.

One way to set up the development environment is to use vite or another framework's dev proxy

server with most requests proxied to KoLmafia and then to KoL itself. So e.g. you would access

the development environment at `http://localhost:3000/game.php`, which would directly serve

resources for your script and proxy all other requests to `127.0.0.1:60080`.

Example vite config from `YORICK` for this setup:

```typescript

{

  plugins: [react()],

  base: '/yorick/',

  server: {

    port: 3000,

    proxy: {

      [`^/(?!yorick/|src/|node_modules/|@react-refresh|@vite|${publicFilesRegex}).*(?>`. Any time the values in the record change, data will be

refreshed. The default behavior if no `characterStateOverride` is provided is to refresh when your turn

count, meat, hp, mp, equipment, familiar, or adventure count change.

## Developer Setup

For testing actual development of tome itself, run

`yarn link /path/to/tome/packages/tome-kolmafia-{lib,mock,react}` in the project that depends on tome.