rs3-api-extended 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mark7625
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,88 @@
-# Temporary Holding Version
+# rs3-api-extended
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Custom helpers for RuneScape 3 plugins. Not part of Jagex's API.
+
+Everything in this package was written for this project. None of it exists in the game client, and none of it is something you can call from a plain Lua plugin. It compiles to Lua and ships inside your plugin under `lua_modules/rs3-api-extended/`. For the client's own API, which this builds on, see `rs3-api-core`.
+
+```ts
+import { definePlugin, on, vars } from "rs3-api-extended";
+```
+
+## definePlugin
+
+Wires the lifecycle globals the client looks for and runs your modules.
+
+```ts
+definePlugin({
+    modules: [login, overlay],
+});
+```
+
+A module is any object with optional `init`, `tick`, `draw` and `shutdown` functions, which in practice means a file of exported functions imported with `import * as`. `definePlugin` assigns `PluginLogic` and `PluginShutdown`, adds `PluginDraw` only if something actually draws, and calls each hook through `pcall` so one module throwing does not stop the others. Errors print once per distinct message, prefixed with the plugin's name from `plugin.json`. Pass `name` to override that prefix, or `onError` to handle failures yourself.
+
+| Option | Default | What it does |
+| --- | --- | --- |
+| `modules` | `[]` | Objects whose `init`, `tick`, `draw` and `shutdown` get called. |
+| `autoUnsubscribe` | `true` | Detach anything still subscribed through `on` once shutdown has run. |
+| `name` | `Plugin.Name` | Prefix on error messages. |
+| `onError` | prints once per message | Called with each hook failure instead. |
+
+## autoUnsubscribe
+
+On shutdown, after every module's own `shutdown` has run, any subscription made through `on` and not already detached is detached for you. It is on by default, so a plugin that only ever subscribes in `init` needs no `shutdown` at all:
+
+```ts
+import { on } from "rs3-api-extended";
+
+export function init() {
+    on(Event.GameStateChanged, onGameState);
+}
+
+function onGameState(event: GameStateChangedEvent) {
+    if (event.newState === GameState.GAME) {
+        Chat.AddMessage(ChatType.GENERAL, "This is a test");
+    }
+}
+```
+
+This only covers `on`. A handler attached with `Event.X.Subscribe(handler)` directly is invisible to it, because nothing recorded the pair, so those stay yours to unsubscribe in `shutdown`. Mixing the two is fine: each `on` subscription is forgotten as soon as its unsubscribe runs, so nothing gets detached twice.
+
+`unsubscribeAll()` is exported if you want to drop every `on` subscription at some other moment, and `autoUnsubscribe: false` turns the shutdown sweep off entirely.
+
+## on
+
+Subscribes to an event. The subscription is live as soon as the call returns, and `definePlugin` will clean it up at shutdown, so most of the time you can ignore the return value.
+
+What it returns is the matching unsubscribe, for when you want to detach before shutdown:
+
+```ts
+let stopListening = () => {};
+
+export function init() {
+    stopListening = on(Event.SkillTransmit, onSkillTransmit);
+}
+
+function onSkillTransmit(event: SkillTransmitEvent) {
+    if (event.newGameplayLevel === 99) {
+        stopListening();
+    }
+}
+```
+
+Calling it twice is harmless, and so is letting shutdown collect it instead.
+
+## vars
+
+The client's `var` table, under a name TypeScript allows, since `var` is a reserved word.
+
+```ts
+const lifepoints = vars.VarPlayer.FromID(13379).value;
+```
+
+## Adding a helper
+
+Worth adding if more than one plugin would use it. Keep it to functions and tables: no classes, no array helper methods, nothing that drags in TypeScriptToLua's runtime, because release builds reject output that references it. Put the source in `src/`, export it from `index.ts`, and the build type-checks it against the core declarations.
+
+## License
+
+[MIT](https://github.com/Mark7625/rs3-api-ts/blob/main/LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+/** @noSelfInFile */
+export { definePlugin, on, unsubscribeAll } from "./plugin";
+export type { Handler, Module, PluginOptions, Subscribable, Unsubscribe } from "./plugin";
+export { vars } from "./vars";

package/dist/index.lua

@@ -0,0 +1,12 @@
+local ____exports = {}
+do
+    local ____plugin = require("plugin")
+    ____exports.definePlugin = ____plugin.definePlugin
+    ____exports.on = ____plugin.on
+    ____exports.unsubscribeAll = ____plugin.unsubscribeAll
+end
+do
+    local ____vars = require("vars")
+    ____exports.vars = ____vars.vars
+end
+return ____exports

package/dist/plugin.d.ts

@@ -0,0 +1,28 @@
+/** @noSelfInFile */
+/** @noSelf */
+export interface Module {
+    init?(): void;
+    tick?(now: number): void;
+    draw?(deltaSecs: number): void;
+    shutdown?(): void;
+}
+/** @noSelf */
+export interface PluginOptions extends Module {
+    name?: string;
+    modules?: Module[];
+    autoUnsubscribe?: boolean;
+    onError?(message: string): void;
+}
+export type Unsubscribe = () => void;
+export type Handler<T> = (event: T) => boolean | void;
+/** @noSelf */
+export interface Subscribable<T> {
+    Subscribe(handler: Handler<T>): void;
+    Unsubscribe(handler: Handler<T>): void;
+}
+/** @noSelf */
+export declare function on<T>(source: Subscribable<T>, handler: Handler<T>): Unsubscribe;
+/** @noSelf */
+export declare function unsubscribeAll(): void;
+/** @noSelf */
+export declare function definePlugin(options: PluginOptions): void;

package/dist/plugin.lua

@@ -0,0 +1,92 @@
+local ____exports = {}
+local tracked = {}
+---
+-- @noSelf
+function ____exports.on(source, handler)
+    source.Subscribe(handler)
+    local entry = {detach = function()
+        pcall(source.Unsubscribe, handler)
+    end}
+    tracked[#tracked + 1] = entry
+    return function()
+        local detach = entry.detach
+        if detach ~= nil then
+            entry.detach = nil
+            detach()
+        end
+    end
+end
+---
+-- @noSelf
+function ____exports.unsubscribeAll()
+    local pending = tracked
+    tracked = {}
+    for ____, entry in ipairs(pending) do
+        local detach = entry.detach
+        if detach ~= nil then
+            entry.detach = nil
+            detach()
+        end
+    end
+end
+---
+-- @noSelf
+function ____exports.definePlugin(options)
+    local name = options.name or Plugin.Name or "plugin"
+    local modules = options.modules or ({})
+    local autoUnsubscribe = options.autoUnsubscribe ~= false
+    local lastError
+    local function report(message)
+        if options.onError ~= nil then
+            options.onError(message)
+        elseif message ~= lastError then
+            lastError = message
+            print((("[" .. name) .. "] ") .. message)
+        end
+    end
+    local function guard(fn, arg)
+        if fn == nil then
+            return
+        end
+        local ok, err = pcall(fn, arg)
+        if not ok then
+            report(tostring(err))
+        end
+    end
+    PluginLogic = function(event)
+        local now = event.logicTick
+        for ____, m in ipairs(modules) do
+            guard(m.tick, now)
+        end
+        guard(options.tick, now)
+    end
+    local hasDraw = options.draw ~= nil
+    for ____, m in ipairs(modules) do
+        if m.draw ~= nil then
+            hasDraw = true
+        end
+    end
+    if hasDraw then
+        PluginDraw = function(event)
+            local delta = event.timeDeltaSecs
+            for ____, m in ipairs(modules) do
+                guard(m.draw, delta)
+            end
+            guard(options.draw, delta)
+        end
+    end
+    PluginShutdown = function()
+        guard(options.shutdown)
+        for ____, m in ipairs(modules) do
+            guard(m.shutdown)
+        end
+        if autoUnsubscribe then
+            guard(____exports.unsubscribeAll)
+        end
+    end
+    for ____, m in ipairs(modules) do
+        guard(m.init)
+    end
+    guard(options.init)
+end
+return ____exports

package/dist/vars.d.ts

@@ -0,0 +1,8 @@
+/** @noSelfInFile */
+/**
+ * The game's `var` global (VarPlayer, VarClient, VarClan, ...), re-exported under a
+ * name TypeScript allows. `var` is a reserved word, so it cannot be declared directly.
+ *
+ *     const lifepoints = vars.VarPlayer.FromID(13379).value;
+ */
+export const vars: VarApi;

package/dist/vars.lua

@@ -0,0 +1 @@
+return { vars = var }

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "rs3-api-extended",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Runtime helpers for RuneScape 3 plugins written in TypeScript: definePlugin, event subscription, and the vars shim. Compiled to readable Lua and bundled into your plugin by rs3-plugin.",
+  "license": "MIT",
+  "author": "Mark7625",
+  "homepage": "https://github.com/Mark7625/rs3-api-ts/tree/main/packages/extended#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Mark7625/rs3-api-ts.git",
+    "directory": "packages/extended"
+  },
+  "bugs": {
+    "url": "https://github.com/Mark7625/rs3-api-ts/issues"
+  },
+  "keywords": [
+    "runescape",
+    "rs3",
+    "plugin",
+    "lua",
+    "typescript-to-lua"
+  ],
+  "main": "./dist/index",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tstl -p tsconfig.json && node scripts/postbuild.js",
+    "prepack": "npm run build"
+  },
+  "peerDependencies": {
+    "rs3-api-core": "^0.1.0"
+  },
+  "devDependencies": {
+    "rs3-api-core": "^0.1.0",
+    "typescript": "6.0.2",
+    "typescript-to-lua": "^1.37.1"
+  }
+}