LogoPixi’VN

Navigazione e mappa

Come definire, organizzare e navigare tra stanze, luoghi e mappe in Pixi'VN, incluse classi personalizzate ed esempi di utilizzo.

Nomenclature

Usually in video games, navigation elements used to identify the position of characters are called room, location (e.g. restaurant, house, hospital, etc.), and map. Per questo motivo vengono utilizzati nomi che seguono questa logica.

Ciò non impedisce di utilizzare questi elementi per gestire la navigazione con la stessa logica ma con termini diversi. Ad esempio, in un gioco ambientato nello spazio in cui il giocatore si sposta tra i pianeti, le stanze possono rappresentare i pianeti, i luoghi i sistemi solari e le mappe la galassia.

Il sistema di navigazione è composto dai seguenti elementi:

  • rooms: Gli elementi fondamentali della navigazione, da cui si deduce la posizione di mc e npc.
  • locations: Un contenitore di stanze.
  • maps: Un contenitore di luoghi.

Il giocatore può muoversi tra le stanze. The location and the map are also determined based on the room in which the player is located.

Inizializzare

Per definire una stanza/luogo/mappa, crea una nuova istanza della classe RoomBaseModel / LocationBaseModel / MapBaseModel (o la tua classe personalizzata) e aggiungila al dizionario stanza/luogo/mappa del gioco quando il gioco viene inizializzato.

It is recommended to import the instances at project startup, see the src/main.ts file.

Per creare una nuova istanza di RoomBaseModel, sono necessari i seguenti parametri:

  • id: Un identificatore univoco (stringa). Utilizzato per fare riferimento alla stanza nel gioco (deve essere univoco).
  • location: Il luogo in cui si trova la stanza.
  • props: Un oggetto con le proprietà della stanza:
    • name (Opzionale): Il nome della stanza.
    • image (Opzionale): URL dell'immagine della stanza.
    • activities (Optional): The activities available in this room.
    • disabled (Opzionale): Se la stanza è disabilitata. You can also pass a Pixi’VN flag name.
    • hidden (Opzionale): Se la stanza è nascosta. You can also pass a Pixi’VN flag name.
    • icon (Opzionale): URL dell'immagine dell'icona della stanza.

Per creare una nuova istanza di LocationBaseModel, sono necessari i seguenti parametri:

  • id: Un identificatore univoco (stringa). Used to reference the location in the game (must be unique).
  • map: The map where the location is.
  • props: An object with the location's properties:
    • name (Optional): The location's name.
    • icon (Optional): The location's icon image URL.
    • activities (Optional): The activities available in this location.
    • disabled (Optional): Whether the location is disabled. You can also pass a Pixi’VN flag name.
    • hidden (Optional): Whether the location is hidden. You can also pass a Pixi’VN flag name.

To create a new instance of MapBaseModel, you need the following parameters:

  • id: Un identificatore univoco (stringa). Used to reference the map in the game (must be unique).
  • props: An object with the map's properties:
    • name (Optional): The map's name.
    • image (Optional): The map's image URL.
    • activities (Optional): The activities available in this map.
import { RegisteredRooms, RoomBaseModel } from "@drincs/nqtr";
import { bed } from "./activity";
import { mcHome } from "./locations";

export const mcRoom = new RoomBaseModel("mc_room", mcHome, {
    name: "MC room",
    image: "location_myroom",
    activities: [bed],
});

export const aliceRoom = new RoomBaseModel("alice_room", mcHome, {
    name: "Alice room",
    image: "location_aliceroom",
});

export const annRoom = new RoomBaseModel("ann_room", mcHome, {
    name: "Ann room",
    image: "location_annroom",
});

export const bathroom = new RoomBaseModel("bathroom", mcHome, {
    name: "Bathroom",
    image: "location_bathroom",
});

export const lounge = new RoomBaseModel("lounge", mcHome, {
    name: "Lounge",
    image: "location_lounge",
});

export const terrace = new RoomBaseModel("terrace", mcHome, {
    name: "Terrace",
    image: "location_terrace",
});

RegisteredRooms.add([mcRoom, aliceRoom, annRoom, bathroom, lounge, terrace]);

RegisteredRooms.add / RegisteredLocations.add / RegisteredMaps.add is required to save the rooms/locations/maps in the game.

You can also create a function to load rooms/locations/maps. The important thing is that it is called at least once before the rooms/locations/maps are used in the game, otherwise they will not be available.

It is also recommended to set the current room during the start of the game.

labels/startLabel.ts
import { navigator } from "@drincs/nqtr";
import { newLabel } from "@drincs/pixi-vn";
import { mcRoom } from "../values/rooms";

const startLabel = newLabel("start", [
    async () => {
        navigator.currentRoom = mcRoom;
        // ... other initialization logic
    },
]);
export default startLabel;

Ottieni

To get a room/location/map by its id, use the RegisteredRooms.get / RegisteredLocations.get / RegisteredMaps.get function.

import { RegisteredRooms } from "@drincs/nqtr";

const mcRoom = RegisteredRooms.get('mc_room');

Ottieni tutti

To get all rooms/locations/maps, use the RegisteredRooms.values / RegisteredLocations.values / RegisteredMaps.values function.

import { RegisteredRooms } from "@drincs/nqtr";

const rooms = RegisteredRooms.values();

As explained above, the player can navigate between rooms, and the current room determines the current location and map.

To navigate to a room, set the navigator.currentRoom property to the desired room instance. This will automatically update the current location and map based on the room's location and map.

import { navigator } from "@drincs/nqtr";
import { mcRoom } from "../values/rooms";

navigator.currentRoom = mcRoom;

Classe personalizzata

Templates

In all templates, the Room / Location / Map class is already defined in the file models/nqtr/Room.ts / models/nqtr/Location.ts / models/nqtr/Map.ts. Puoi utilizzarla direttamente o modificarla in base alle tue esigenze.

It is recommended to create your own class Room / Location / Map that extends RoomStoredClass / LocationStoredClass / MapStoredClass and "override" the interface RoomInterface / LocationInterface / MapInterface to add, edit, or remove properties or methods.

For example, if you want to create a class Room / Location / Map, you must "override" the interface RoomInterface / LocationInterface / MapInterface to use your properties or methods. (See the file nqtr.d.ts)

Now you can create a class Room / Location / Map that extends RoomStoredClass / LocationStoredClass / MapStoredClass and implements the RoomInterface / LocationInterface / MapInterface. (Per maggiori informazioni su come creare una classe in TypeScript, leggi la documentazione ufficiale)

To create a property that stores its value in the game storage, you can create Getters/Setters and use the this.getStorageProperty() / this.setStorageProperty() methods. (See the file Room.ts / Location.ts / Map.ts)

import { ActivityInterface, LocationInterface, OnRunProps, RoomInterface, RoomStoredClass } from "@drincs/nqtr";

export default class Room extends RoomStoredClass implements RoomInterface {
    constructor(
        id: string,
        location: LocationInterface,
        props: {
            name: string;
            disabled?: boolean | (() => boolean);
            hidden?: boolean | (() => boolean);
            background: string | ContainerChild | ((props: Room, runProps: OnRunProps) => ContainerChild);
            activities?: ActivityInterface[];
            isEntrance?: boolean;
        }
    ) {
        super(id, location, props.activities);
        this.name = props.name;
        this._defaultDisabled = props.disabled || false;
        this._defaultHidden = props.hidden || false;
        this._background = props.background;
        this.isEntrance = props.isEntrance || false;
    }
    readonly name: string;
    private readonly _background: string | ContainerChild | ((props: Room, runProps: OnRunProps) => ContainerChild);
    get background(): string | ContainerChild | ((props: OnRunProps) => ContainerChild) {
        const background = this._background;
        if (typeof background === "function") {
            return (runProps: OnRunProps) => background(this, runProps);
        }
        return background;
    }
    readonly isEntrance: boolean;
    private _defaultDisabled: boolean | (() => boolean) = false;
    get disabled(): boolean {
        let value = this.getStorageProperty<boolean>("disabled") || this._defaultDisabled;
        if (typeof value === "function") {
            return value();
        }
        return value;
    }
    set disabled(value: boolean) {
        this.setStorageProperty("disabled", value);
    }
    private _defaultHidden: boolean | (() => boolean) = false;
    get hidden(): boolean {
        let value = this.getStorageProperty<boolean>("hidden") || this._defaultHidden;
        if (typeof value === "function") {
            return value();
        }
        return value;
    }
    set hidden(value: boolean) {
        this.setStorageProperty("hidden", value);
    }
}

FAQ