PkgFoundry
Catalog npm
Back to packageRELEASE DETAILS

0.1.1

npm

@0xspencer/ready-agent-one

A framework giving AI agents a toolkit to interact meaningfully in a game world.

aiframeworkgame developmenttypescript
Published5 Feb 2025
Direct dependencies284
Transitive dependenciesNot calculated

README

Current package documentation

ready-agent-one

ready-agent-one is a framework for giving AI agents a novel way to interact meaningfully in a game world. It provides a structure to handle world (server) ticks and world events, allowing you to easily manage, customize, and process game events involving players.

It's purpose is to define a standard (and provide necessary tooling to work within that standard) to intercept in-game world information and events with the purpose of controlling agent prompting and extending behavior beyond typical action schemas.

Features

  • World Ticks: Keep track of ongoing gameplay and player statuses.
  • World Events: Trigger specific game actions such as player entry, exit, or winning events.
  • Custom Events: Specify custom world events from the game.
  • Customizable Callbacks: Easily register and trigger event handlers for various game actions.
  • TypeScript Support: Fully typed API to ensure reliability and clarity

Installation

To install ready-agent-one, run the following command:

npm install ready-agent-one

Usage

  1. Importing the library
import { tryParseWorldMessage, setOnWorldTickCallback, registerEventAction } from 'ready-agent-one';
import { PLAYER_ENTER_EVENT, PLAYER_EXIT_EVENT } from 'ready-agent-one/dist/types/sharedTypes';
  1. Set up the world tick handler
setOnWorldTickCallback((message) => {
  const presentPlayers = message.players;

  agent.updateWorldInfo(`Present players: ${presentPlayers.map(player => player.username).join(', ');}`)
});
  1. Register event actions
registerEventAction(PLAYER_ENTER_EVENT, (data) => {
  console.log('Player entered:', data.username);

  // handle agent response for player entering a zone (eg: award player with an NFT or a Superfluid stream)
  agent.promptSuperfluidStream(data.username, data.walletAddress);
});

registerEventAction(PLAYER_EXIT_EVENT, (data) => {
  console.log('Player exited:', data.username);

  // handle agent response for player exiting a zone (eg: stop a Superfluid stream)
});
  1. Parse incoming game messages You can parse game messages (either world ticks or events) using tryParseWorldMessage:
const messageFromGame = {
  text: 'WORLD_TICK',
  players: [{ userId: '1234', username: 'Player1' }],
};

const parseSuccessful = tryParseWorldMessage(messageFromGame); // Triggers onWorldTick callback

if (!parseSuccessful) {
    // if parse not successful, this is not a world message, and the agent can reply as they please
} else {
  agent.respond(messageFromGame);
}

API

tryParseWorldMessage(json: any): json is WorldMessage Parses an incoming game message and triggers the appropriate callbacks based on whether it's a WORLD_TICK or WORLD_EVENT.

Parameters:

  • json: The incoming message (can be either a world tick or world event). Returns:
  • true if the message was successfully parsed and processed.
  • false if the message does not match a valid WORLD_TICK or WORLD_EVENT.

setOnWorldTickCallback(callback: (message: WorldTick) => void): void Sets a callback function that will be called whenever a WORLD_TICK message is received.

Parameters:

  • callback: The function to call when a world tick message is received. It receives the parsed WorldTick.

registerEventAction(eventName: EventName, callback: EventCallback): void Registers an action callback for a specific event.

Parameters:

  • eventName: The name of the event to listen for (e.g., PLAYER_ENTER).
  • callback: The function to call when the event is triggered. It receives the eventData associated with the event.

Types

WorldTick Represents a world tick message that contains player information.

{
  text: "WORLD_TICK";
  players: Player[];
}

WorldEvent Represents a world event message. There are different types of events, such as PLAYER_ENTER, PLAYER_EXIT, and PLAYER_WON. You can also specify a custom event and eventData.

{
  text: "WORLD_EVENT";
  event: EventName;
  eventData: object;
}

Player Represents a player object with a userId and username.

{
  userId: string;
  username: string;
}

Standard

The ready-agent-one standard supports 2 primary messages, defined as WorldMessages:

  • WorldTick
  • WorldEvent

It boils down to defining a message and a callback to that method. The event callback then decides if the message context is appropriate to pass to the agent.

WorldTick

The WorldTick is a message sent from the game authority (usually the game server) on a specified interval to inform the agent of the current game state. Currently it supports a list of active players, but its interface is extendible.

WorldEvent

The WorldEvent message is sent whenever something noteworthy happens in game. It contains a unique EventName that identifies the context of the event. Furthermore, it contains an eventData object with additional context on the event.

Below are the currently supported events, with eventData contexts:

EventEvent Data
PLAYER_ENTER{ player: Player, zoneId: string }
PLAYER_EXIT{ player: Player, zoneId: string }
PLAYER_WON{ player: Player, score: numer, game: string }
GAME_COMPLETED_EVENT{ rank: Player[], game: string }

While some events are standardized and included in this package, any event name can be manually added and configured (as long as the game supports it).

registerEventAction("CUSTOM_EVENT_NAME", OnCustomEventCallback)

Testing

npm test

Roadmap

  • Python package
  • Node/Python package for three.js and pygame game servers for easy message sending
  • Extending functionality and events

Downloads & popularity

Awaiting observations

No metric observations yet

Download counts and popularity will appear here as the collector receives them.

Declared dependencies 284

Native requirements
284 direct targetsNot calculated transitive count
Package / targetRequirementRelationship
co
Environment
{
  "local_name": "co",
  "alias": false,
  "peer_metadata": null
}
^4.6.0runtime
ms
Environment
{
  "local_name": "ms",
  "alias": false,
  "peer_metadata": null
}
^2.1.3runtime
yn
Environment
{
  "local_name": "yn",
  "alias": false,
  "peer_metadata": null
}
^3.1.1runtime
ajv
Environment
{
  "local_name": "ajv",
  "alias": false,
  "peer_metadata": null
}
^6.12.6runtime
arg
Environment
{
  "local_name": "arg",
  "alias": false,
  "peer_metadata": null
}
^4.1.3runtime
cac
Environment
{
  "local_name": "cac",
  "alias": false,
  "peer_metadata": null
}
^6.7.14runtime
ejs
Environment
{
  "local_name": "ejs",
  "alias": false,
  "peer_metadata": null
}
^3.1.10runtime
ufo
Environment
{
  "local_name": "ufo",
  "alias": false,
  "peer_metadata": null
}
^1.5.4runtime
bser
Environment
{
  "local_name": "bser",
  "alias": false,
  "peer_metadata": null
}
^2.1.1runtime
chai
Environment
{
  "local_name": "chai",
  "alias": false,
  "peer_metadata": null
}
^4.5.0runtime
diff
Environment
{
  "local_name": "diff",
  "alias": false,
  "peer_metadata": null
}
^4.0.2runtime
exit
Environment
{
  "local_name": "exit",
  "alias": false,
  "peer_metadata": null
}
^0.1.2runtime
glob
Environment
{
  "local_name": "glob",
  "alias": false,
  "peer_metadata": null
}
^7.2.3runtime
jake
Environment
{
  "local_name": "jake",
  "alias": false,
  "peer_metadata": null
}
^10.9.2runtime
jest
Environment
{
  "local_name": "jest",
  "alias": false,
  "peer_metadata": null
}
^29.7.0runtime
keyv
Environment
{
  "local_name": "keyv",
  "alias": false,
  "peer_metadata": null
}
^4.5.4runtime
levn
Environment
{
  "local_name": "levn",
  "alias": false,
  "peer_metadata": null
}
^0.4.1runtime
mlly
Environment
{
  "local_name": "mlly",
  "alias": false,
  "peer_metadata": null
}
^1.7.4runtime
once
Environment
{
  "local_name": "once",
  "alias": false,
  "peer_metadata": null
}
^1.4.0runtime
tmpl
Environment
{
  "local_name": "tmpl",
  "alias": false,
  "peer_metadata": null
}
^1.0.5runtime
vite
Environment
{
  "local_name": "vite",
  "alias": false,
  "peer_metadata": null
}
^5.4.14runtime
y18n
Environment
{
  "local_name": "y18n",
  "alias": false,
  "peer_metadata": null
}
^5.0.8runtime
acorn
Environment
{
  "local_name": "acorn",
  "alias": false,
  "peer_metadata": null
}
^8.14.0runtime
async
Environment
{
  "local_name": "async",
  "alias": false,
  "peer_metadata": null
}
^3.2.6runtime
chalk
Environment
{
  "local_name": "chalk",
  "alias": false,
  "peer_metadata": null
}
^4.1.2runtime
cliui
Environment
{
  "local_name": "cliui",
  "alias": false,
  "peer_metadata": null
}
^8.0.1runtime
debug
Environment
{
  "local_name": "debug",
  "alias": false,
  "peer_metadata": null
}
^4.4.0runtime
execa
Environment
{
  "local_name": "execa",
  "alias": false,
  "peer_metadata": null
}
^8.0.1runtime
fastq
Environment
{
  "local_name": "fastq",
  "alias": false,
  "peer_metadata": null
}
^1.19.0runtime
isexe
Environment
{
  "local_name": "isexe",
  "alias": false,
  "peer_metadata": null
}
^2.0.0runtime
jsesc
Environment
{
  "local_name": "jsesc",
  "alias": false,
  "peer_metadata": null
}
^3.1.0runtime
json5
Environment
{
  "local_name": "json5",
  "alias": false,
  "peer_metadata": null
}
^2.2.3runtime
kleur
Environment
{
  "local_name": "kleur",
  "alias": false,
  "peer_metadata": null
}
^3.0.3runtime
leven
Environment
{
  "local_name": "leven",
  "alias": false,
  "peer_metadata": null
}
^3.1.0runtime
loupe
Environment
{
  "local_name": "loupe",
  "alias": false,
  "peer_metadata": null
}
^2.3.7runtime
p-try
Environment
{
  "local_name": "p-try",
  "alias": false,
  "peer_metadata": null
}
^2.2.0runtime
pathe
Environment
{
  "local_name": "pathe",
  "alias": false,
  "peer_metadata": null
}
^1.1.2runtime
slash
Environment
{
  "local_name": "slash",
  "alias": false,
  "peer_metadata": null
}
^3.0.0runtime
which
Environment
{
  "local_name": "which",
  "alias": false,
  "peer_metadata": null
}
^2.0.2runtime
yargs
Environment
{
  "local_name": "yargs",
  "alias": false,
  "peer_metadata": null
}
^17.7.2runtime
braces
Environment
{
  "local_name": "braces",
  "alias": false,
  "peer_metadata": null
}
^3.0.3runtime
dedent
Environment
{
  "local_name": "dedent",
  "alias": false,
  "peer_metadata": null
}
^1.5.3runtime
espree
Environment
{
  "local_name": "espree",
  "alias": false,
  "peer_metadata": null
}
^9.6.1runtime
expect
Environment
{
  "local_name": "expect",
  "alias": false,
  "peer_metadata": null
}
^29.7.0runtime
hasown
Environment
{
  "local_name": "hasown",
  "alias": false,
  "peer_metadata": null
}
^2.0.2runtime
ignore
Environment
{
  "local_name": "ignore",
  "alias": false,
  "peer_metadata": null
}
^5.3.2runtime
merge2
Environment
{
  "local_name": "merge2",
  "alias": false,
  "peer_metadata": null
}
^1.4.1runtime
nanoid
Environment
{
  "local_name": "nanoid",
  "alias": false,
  "peer_metadata": null
}
^3.3.8runtime
rimraf
Environment
{
  "local_name": "rimraf",
  "alias": false,
  "peer_metadata": null
}
^3.0.2runtime
rollup
Environment
{
  "local_name": "rollup",
  "alias": false,
  "peer_metadata": null
}
^4.34.1runtime
semver
Environment
{
  "local_name": "semver",
  "alias": false,
  "peer_metadata": null
}
^7.7.0runtime
uri-js
Environment
{
  "local_name": "uri-js",
  "alias": false,
  "peer_metadata": null
}
^4.4.1runtime
walker
Environment
{
  "local_name": "walker",
  "alias": false,
  "peer_metadata": null
}
^1.0.8runtime
wrappy
Environment
{
  "local_name": "wrappy",
  "alias": false,
  "peer_metadata": null
}
^1.0.2runtime
ci-info
Environment
{
  "local_name": "ci-info",
  "alias": false,
  "peer_metadata": null
}
^3.9.0runtime
confbox
Environment
{
  "local_name": "confbox",
  "alias": false,
  "peer_metadata": null
}
^0.1.8runtime
deep-is
Environment
{
  "local_name": "deep-is",
  "alias": false,
  "peer_metadata": null
}
^0.1.4runtime
esbuild
Environment
{
  "local_name": "esbuild",
  "alias": false,
  "peer_metadata": null
}
^0.21.5runtime
esprima
Environment
{
  "local_name": "esprima",
  "alias": false,
  "peer_metadata": null
}
^4.0.1runtime
esquery
Environment
{
  "local_name": "esquery",
  "alias": false,
  "peer_metadata": null
}
^1.6.0runtime
esutils
Environment
{
  "local_name": "esutils",
  "alias": false,
  "peer_metadata": null
}
^2.0.3runtime
find-up
Environment
{
  "local_name": "find-up",
  "alias": false,
  "peer_metadata": null
}
^5.0.0runtime
flatted
Environment
{
  "local_name": "flatted",
  "alias": false,
  "peer_metadata": null
}
^3.3.2runtime
gensync
Environment
{
  "local_name": "gensync",
  "alias": false,
  "peer_metadata": null
}
^1.0.0-beta.2runtime
globals
Environment
{
  "local_name": "globals",
  "alias": false,
  "peer_metadata": null
}
^15.14.0runtime
is-glob
Environment
{
  "local_name": "is-glob",
  "alias": false,
  "peer_metadata": null
}
^4.0.3runtime
js-yaml
Environment
{
  "local_name": "js-yaml",
  "alias": false,
  "peer_metadata": null
}
^4.1.0runtime
onetime
Environment
{
  "local_name": "onetime",
  "alias": false,
  "peer_metadata": null
}
^6.0.0runtime
p-limit
Environment
{
  "local_name": "p-limit",
  "alias": false,
  "peer_metadata": null
}
^3.1.0runtime
pathval
Environment
{
  "local_name": "pathval",
  "alias": false,
  "peer_metadata": null
}
^1.1.1runtime
pirates
Environment
{
  "local_name": "pirates",
  "alias": false,
  "peer_metadata": null
}
^4.0.6runtime
pkg-dir
Environment
{
  "local_name": "pkg-dir",
  "alias": false,
  "peer_metadata": null
}
^4.2.0runtime
postcss
Environment
{
  "local_name": "postcss",
  "alias": false,
  "peer_metadata": null
}
^8.5.1runtime
prompts
Environment
{
  "local_name": "prompts",
  "alias": false,
  "peer_metadata": null
}
^2.4.2runtime
resolve
Environment
{
  "local_name": "resolve",
  "alias": false,
  "peer_metadata": null
}
^1.22.10runtime
reusify
Environment
{
  "local_name": "reusify",
  "alias": false,
  "peer_metadata": null
}
^1.0.4runtime
siginfo
Environment
{
  "local_name": "siginfo",
  "alias": false,
  "peer_metadata": null
}
^2.0.0runtime
std-env
Environment
{
  "local_name": "std-env",
  "alias": false,
  "peer_metadata": null
}
^3.8.0runtime
tinyspy
Environment
{
  "local_name": "tinyspy",
  "alias": false,
  "peer_metadata": null
}
^2.2.1runtime
ts-jest
Environment
{
  "local_name": "ts-jest",
  "alias": false,
  "peer_metadata": null
}
^29.2.5runtime
yallist
Environment
{
  "local_name": "yallist",
  "alias": false,
  "peer_metadata": null
}
^3.1.1runtime
anymatch
Environment
{
  "local_name": "anymatch",
  "alias": false,
  "peer_metadata": null
}
^3.1.3runtime
argparse
Environment
{
  "local_name": "argparse",
  "alias": false,
  "peer_metadata": null
}
^2.0.1runtime
deep-eql
Environment
{
  "local_name": "deep-eql",
  "alias": false,
  "peer_metadata": null
}
^4.1.4runtime
doctrine
Environment
{
  "local_name": "doctrine",
  "alias": false,
  "peer_metadata": null
}
^3.0.0runtime
emittery
Environment
{
  "local_name": "emittery",
  "alias": false,
  "peer_metadata": null
}
^0.13.1runtime
error-ex
Environment
{
  "local_name": "error-ex",
  "alias": false,
  "peer_metadata": null
}
^1.3.2runtime
escalade
Environment
{
  "local_name": "escalade",
  "alias": false,
  "peer_metadata": null
}
^3.2.0runtime
filelist
Environment
{
  "local_name": "filelist",
  "alias": false,
  "peer_metadata": null
}
^1.0.4runtime
has-flag
Environment
{
  "local_name": "has-flag",
  "alias": false,
  "peer_metadata": null
}
^4.0.0runtime
inflight
Environment
{
  "local_name": "inflight",
  "alias": false,
  "peer_metadata": null
}
^1.0.6runtime
inherits
Environment
{
  "local_name": "inherits",
  "alias": false,
  "peer_metadata": null
}
^2.0.4runtime
jest-cli
Environment
{
  "local_name": "jest-cli",
  "alias": false,
  "peer_metadata": null
}
^29.7.0runtime
make-dir
Environment
{
  "local_name": "make-dir",
  "alias": false,
  "peer_metadata": null
}
^4.0.0runtime
mimic-fn
Environment
{
  "local_name": "mimic-fn",
  "alias": false,
  "peer_metadata": null
}
^4.0.0runtime
p-locate
Environment
{
  "local_name": "p-locate",
  "alias": false,
  "peer_metadata": null
}
^5.0.0runtime
path-key
Environment
{
  "local_name": "path-key",
  "alias": false,
  "peer_metadata": null
}
^3.1.1runtime
punycode
Environment
{
  "local_name": "punycode",
  "alias": false,
  "peer_metadata": null
}
^2.3.1runtime
react-is
Environment
{
  "local_name": "react-is",
  "alias": false,
  "peer_metadata": null
}
^18.3.1runtime
tinypool
Environment
{
  "local_name": "tinypool",
  "alias": false,
  "peer_metadata": null
}
^0.8.4runtime

Showing the first 100 declarations.

Distribution files

1 collected
Distribution 1

Source distribution

Source file
Checksums from source
{
  "shasum": "c431253dff4475d3c8b775816be5f325c1a2552c",
  "tarball": "https://registry.npmjs.org/@0xspencer/ready-agent-one/-/ready-agent-one-0.1.1.tgz",
  "fileCount": 15,
  "integrity": "sha512-AjWuprQpGuo+e4DQdjqN6woceeL/7Z6dvuy1jA7ffz5t5Grx2QbrvbIT3l1JiuIHLEWmd/NO8+mQfdK0GVSgHw==",
  "signatures": [
    {
      "sig": "MEUCICwJUHszE9lplOwsQzZKy/Uy62X9Q0goHttRvtW8hZK9AiEA7EVEvv3CoVSwQ5aOiqcSkS1O66yIzthPo9xbutsOPe4=",
      "keyid": "SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"
    }
  ],
  "unpackedSize": 33606
}

Repository

PENDING
gtspencer/ready-agent-one

Shared repository data · GitHub

License detected in repository
Not collected

Metadata history

Meaningful changes
Current collected state Current

Observed since 21 Oct, 11:36 UTC

No superseded metadata states collected. Unchanged observations do not create new revisions.

Record identity

package_version:69d3d98686daa0e103cd152df78b23a3355fb4aa7e82c7ec19822b008ca2cdb5

Other collected versions

0.1.55 Feb0.1.45 Feb0.1.35 Feb0.1.25 Feb0.1.05 FebView all collected versions →