The built bundles are committed, so the build folder is not disposable

Seven subsystems and eleven example folders

The feature list is seven lines long and each one has a matching example directory in the repository, which is the clearest way to size the project. Autonomous agent design covers a basic game entity concept plus classes for state-driven and goal-driven agent design. Steering provides a built-in vehicle model and steering behaviors. Navigation provides graph classes, search algorithms and a navigation mesh implementation for path finding. Perception gives entities a short-term memory and a vision component. Triggers generate dynamic actions in the game. Fuzzy logic is a fuzzy inference system for making entities smarter. JSON is a serialization and deserialization API for saving and loading game state. The examples directory holds fsm, fuzzy, goal, graph, lib, math, misc, navigation, perception, playground and steering, which is eleven folders for seven features, so some features carry more than one demonstration and a couple of folders cover supporting concerns. Read that list as a curriculum: each folder is a self-contained demonstration of one idea.

Engine independence is the constraint that shapes everything

The README states that Yuka is a standalone library independent of a particular 3D engine, and that sentence explains several other choices. Because it does not own your scene graph, its steering behaviors and navigation mesh work on data you feed them rather than on engine objects, which means an adapter layer between your entities and Yuka's interfaces. In exchange, the same AI code runs whether your game is built on a WebGL renderer, on a framework or on something you wrote. The vehicle model is built in rather than assumed from an engine's physics, so it is a model you get for free and a model you can inspect, which for learning purposes is the better trade. The practical consequence is that vector math, spatial queries and mesh handling belong to Yuka rather than to your engine, and if your engine already has a good navmesh you may be maintaining two.

package.json points at files inside a committed build directory

The manifest makes an unusual choice worth noticing before you debug an install. main is build/yuka.js and module is build/yuka.module.js, so consumers load prebuilt bundles rather than the source tree, and build/ appears as a tracked entry in the repository listing. That means the shipped artifact is whatever was built and committed, not whatever your npm install or your toolchain produces, and it means a diff touching build/ is a diff touching the shipped library. The build itself is two rollup invocations, one for the development build and one for the production build through separate config files, with a plugin that stamps the legal banner and terser for minification, so both are applied by the bundler rather than by hand. A version field of 0.7.8 in the manifest is what you get from npm, and with no published build tags to compare, that manifest is the only version marker.

npm install and npm start bring up the examples

If you download the repository and run npm install and npm start in the main directory, a local server starts and the examples are available in your browser. What npm start actually runs is worth knowing: it is an alias for npm run dev, and dev is a concurrently invocation that runs rollup in watch mode alongside a static server. So the examples are served from a working build that rebuilds as you change source, which is a development setup rather than a way to browse a published package. Documentation is generated separately with jsdoc over src using a config file, and the jsdoc output uses the tui-jsdoc-template package. Tests are mocha with nyc for coverage, run against test/unit_test, and lint is eslint over src and examples with the mdcs config and the html plugin, which is why the eslintIgnore list contains yuka.module.js, three.module.js and dat.gui.module.js.

State-driven and goal-driven agents are the two starting points

Autonomous agent design is where a new user actually begins, and the README names two families.

npm install && npm start

That is the whole local setup, and it is worth running before reading anything else. State-driven agents react to what they perceive, and the perception module gives an entity a short-term memory and a vision component to feed that. Goal-driven agents work backwards from a desired outcome, which is where the navigation module earns its place: graph classes, search algorithms and a navigation mesh implementation give the agent something to plan a path over. Triggers sit alongside both, generating dynamic actions rather than requiring behavior to be hard-coded in the entity. Fuzzy logic is the optional extra, a fuzzy inference system for expressing judgment rather than a threshold comparison. The fsm and goal example folders are where the relationship between these pieces is clearest, so start there.

Saving the game is a JSON serialization call

The last feature on the list is the one that decides whether the library is usable in a shipping game rather than a demo. Save and load the current state of your game through a serialization and deserialization API based on JSON, which means the AI state is portable, inspectable and diffable, and a saved file can be read without the library loaded. The design follows from engine independence: if the AI state were tied to engine objects, serializing it would require the engine to be present, and JSON keeps the boundary clean. It also has a limit worth naming, which is that whatever your entities hold outside Yuka is not covered by this API, so a full save still needs your own code for the parts the library never saw. The documentation and the examples are both published on the project site, and a Discord server exists for questions about Yuka and game AI topics.

Where Yuka is the wrong choice

Four cases. The first is a project inside an engine that already has this. An engine with a built-in agent system, steering and navmesh means Yuka duplicates it, and the adapter layer becomes the maintenance burden rather than the abstraction. The second is a team that wants its AI state in a binary or schema-validated format. The state API is JSON, which is good for inspection and bad for large or highly repetitive state, and there is no other format described. The third is a TypeScript project expecting types. There is a main and a module field and no types entry, and the source is JavaScript, so editor completion and type safety come from documentation rather than from declarations. The fourth is expecting a maintained ecosystem around a specific topic. The recommended reading list is two books, Programming Game AI by Example and the 3D Math Primer for Graphics and Game Development, which tells you the concepts were current when the library was designed, and with no published build tags, the moving npm version is the only signal of ongoing work.

Editorial conclusion

Yuka suits a JavaScript developer building a game with a custom entity system who wants steering, path finding and perception without tying the AI layer to a 3D engine. It does not suit a project already inside an engine that ships its own AI components, nor a TypeScript team expecting type declarations from the package. Before adopting, run npm install and npm start to browse the examples, read the goal and graph examples before the steering ones, and check that the committed build output matches what you would produce from source.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Mugen87/yuka on GitHub
4. Project website
5. README