drincs-productions/nqtr

nqtr-navigation

Use when defining or navigating NQTR rooms, locations and maps — RoomBaseModel/LocationBaseModel/MapBaseModel, RegisteredRooms/RegisteredLocations/RegisteredMaps, navigator.currentRoom, " enter room" in ink, entrance rooms, and custom Room/Location/Map clas…

View source

How to use

  1. Copy the installation command and review the source package before installing it in your own agent environment.
  2. Check the source document for required tools, credentials and supported hosts.
  3. Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/drincs-productions/nqtr --skill nqtr-navigation

Before you start

  • Installation does not include a model subscription, API allowance or permission to access your files.
  • Repository stars and installation counts describe activity, not an independent quality or security test.
Original skill document

Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.

NQTR navigation and map

Official docs: pixi-vn.com/nqtr/navigation. Index: nqtr. Prefer ink for story-side navigation when the project uses ink: nqtr-ink.

Concepts

ElementRole
roomThe core element; the position of the MC and NPCs is deduced from it
locationContainer of rooms
mapContainer of locations

The player moves between rooms; the current location and map are derived from the current room. The terms are conventional (in a space game: planets/solar systems/galaxy).

Initialize

Create map → location → room (each needs its parent) and register them. Registered*.add is required.

ts
import { MapBaseModel, RegisteredMaps } from "@drincs/nqtr";

export const mainMap = new MapBaseModel("main_map", { name: "Main Map", image: "map" });
RegisteredMaps.add(mainMap);
ts
import { LocationBaseModel, RegisteredLocations } from "@drincs/nqtr";
import { mainMap } from "@/content/maps";

export const mcHome = new LocationBaseModel("mc_home", mainMap, { name: "MC Home" });
RegisteredLocations.add(mcHome);
ts
import { RegisteredRooms, RoomBaseModel } from "@drincs/nqtr";
import { mcHome } from "@/content/locations";

export const mcRoom = new RoomBaseModel("mc_room", mcHome, {
    name: "MC room",
    image: "location_myroom",
    activities: ["bed"],          // see nqtr-activity
});
export const aliceRoom = new RoomBaseModel("alice_room", mcHome, {
    name: "Alice room",
    image: "location_aliceroom",
    routine: ["alice_sleep"],     // see nqtr-routine
});
RegisteredRooms.add(mcRoom, aliceRoom);

Import order: content files that reference each other must not form cycles; the parent (map, then location) is imported by the child.

Get / get all

RegisteredRooms.get(id), RegisteredLocations.get(id), RegisteredMaps.get(id); .values() returns all. navigator.rooms/locations/maps list the registered entities.

Navigate

Set the current room; location and map update automatically. Do it at game start too.

ink
=== start ===
# enter room mc_room
-> DONE
ts
import { navigator } from "@drincs/nqtr";
navigator.currentRoom = mcRoom;            // accepts a room or its id
navigator.currentRoomId; navigator.currentLocation; navigator.currentMap;

navigator.clearExpiredActivities() drops activities whose schedule ended.

Custom classes

Extend RoomStoredClass / LocationStoredClass / MapStoredClass, implement the matching interface, and augment it in nqtr.d.ts (name, sprite/background, disabled, hidden, entrance, ...). Constructor shapes: Room(id, location, { activities?, routine? }), Location(id, map, activities?), Map(id, activities?). Store mutable flags with getStorageProperty/setStorageProperty:

ts
export default class Room extends RoomStoredClass implements RoomInterface {
    constructor(id: string, location: LocationInterface, props: { name: string; activities?: (ActivityInterface | ActivityIdType)[]; routine?: (CommitmentInterface | CommitmentIdType)[]; isEntrance?: boolean }) {
        super(id, location, { activities: props.activities || [], routine: props.routine || [] });
        this.name = props.name;
        this.isEntrance = props.isEntrance || false;
    }
    readonly name: string;
    readonly isEntrance: boolean;
    get hidden(): boolean { return this.getStorageProperty<boolean>("hidden") || false; }
    set hidden(value: boolean) { this.setStorageProperty("hidden", value); }
}

Graphical elements (background, sprite, icon)

  • background accepts a string (the alias of a linked asset) or a TimeSlotsImage (see time) to change the image by time of day.
  • sprite accepts either a string (the alias of a linked asset) or a function returning a PixiJS element (e.g. a Sprite with eventMode: "static" and a pointerdown handler) when you need full control.
  • icon is a function returning a UI element (e.g. a React button).

Default ("entrance") room of a location

Add isEntrance to Room (and RoomInterface), and in Location expose get entrance() returning super.rooms.find((r) => r.isEntrance) || super.rooms[0] (or undefined if empty). A map UI then does navigator.currentRoom = location.entrance when the location icon is clicked.

Pitfalls

  • Forgetting Registered*.add: the room cannot be saved or entered from ink.
  • Overriding rooms/locations getters to filter hidden is common; remember hidden rooms are then absent from location.rooms.
from this repository

More skills

All skills
drincs-productions
Community

nqtr

Index and entry point of the NQTR skill set — start here for any task on a project using @drincs/nqtr (Navigation Quest Time Routine), then follow the skill map to the right skill (navigation, time, activity, routine, quest, ink). Use when installing/configuring @drincs/nqtr, wiring vitePluginNqtr, overriding OnRunProps or the Interface types in nqtr.d.ts, writing custom Room/Location/Map/Activity/Commitment/Quest classes, or deciding whether to write NQTR logic in ink or TypeScript.

1h installs
3
GitHub stars
2
Updated
Nov 17
drincs-productions
Community

nqtr-activity

Use when creating NQTR activities (actions the player can take, linked to rooms/locations/maps) — ActivityBaseModel, RegisteredActivities, linking at init (activities in the room constructor) vs at runtime (room.addActivity / " add activity X in room"), unlinking, timeSlot/dateScheduling, disabled/hidden, and custom Activity classes.

1h installs
3
GitHub stars
2
Updated
Nov 17
drincs-productions
Community

nqtr-ink

Use when writing .ink files in a Pixi'VN project that uses @drincs/nqtr — every NQTR hashtag command ( enter room, set time, set date, wait, add/remove activity, add/remove routine, start/continue quest) and the quest state variables (questIdstarted, completed, failed, currentStageIndex), plus createNqtrHandler setup and options. Prefer this over TypeScript labels whenever ink is configured.

1h installs
3
GitHub stars
2
Updated
Nov 17
drincs-productions
Community

nqtr-quest

Use when creating or driving NQTR quests — QuestBaseModel with StageBaseModel stages (onStart, deltaDateRequired, flags, questsRequired), RegisteredQuests, start/continue/advanceIfCompleted, failing a quest, state queries (started, completed, failed, currentStageIndex) and the ink commands " start quest", " continue quest" with the questIdstarted / currentStageIndex variables.

1h installs
3
GitHub stars
2
Updated
Nov 17