Pixi’VN
Make your first

Point & Click Adventure

Before continuing, it is important to consider that this page assumes the concepts explained in "Make your first Visual Novel", and that all the features explained on that page can also be applied here. Additionally, having an intermediate knowledge of JS/TS (such as functions, classes, interfaces, and the use of .d.ts files) is essential. Do not continue if you do not have this knowledge.

This tutorial will guide you through the process of creating your first Point & Click Adventure.

Additionally, it is very important to consider that elements can trigger labels (narratives), allowing you to switch to the narrative interface and back.

Create a new project

Before starting, make sure you have installed the prerequisites.

The first step is to create a new project. You can do this by running:

npm create pixi-vn@latest

and selecting the Point & Click Adventure template.

VS Code

If you open the project with VS Code, you will be asked to consent to running some workspace tasks and to install the recommended extensions for the project. It is strongly advised to accept both.

You can find more information about templates, tasks, and extensions here.

Add clickable elements

The main feature of a Point & Click Adventure is the ability to interact with the environment through mouse clicks. To add clickable elements, it is recommended to use UI (in our case React or PixiJS) rather than the Pixi’VN canvas, as it is easier to manage events and interactions.

In the template we are using, when creating the elements that we will see later, there is the possibility to define graphical elements (such as an icon). These graphical elements can be defined using different types; based on this, the system will add the graphical element to the PixiJS UI or to the React UI. In this way, it is possible to create clickable elements in a simple and fast way.

You can find more detailed documentation about these elements here.

The first step to create a Point & Click Adventure is to create the navigation elements. These elements allow the player to move within the game and interact with the environment.

The navigation system is composed of the following elements:

ElementDescription
roomsThe core elements of navigation, from which the position of the mc and npc is deduced.
locationsA container of rooms.
mapsA container of locations.

For example:

content/rooms.tsx
import { mcHome } from "@/content/locations";
import Room from "@/models/Room";
import TimeSlotsImage from "@/models/TimeSlotsImage";
import { navigator, RegisteredRooms } from "@drincs/nqtr";

export const mcRoomBackground = new TimeSlotsImage({
    morning: "location_myroom-0",
    afternoon: "location_myroom-1",
    evening: "location_myroom-2",
    night: "location_myroom-3",
});
export const mcRoom = new Room("mc_room", mcHome, {
    name: "MC room",
    background: mcRoomBackground,
    activities: ["bed"],
});

RegisteredRooms.add(mcRoom);

// default room to prevent errors when accessing navigator.currentRoom before any room is loaded.
navigator.currentRoom = mcRoom;
content/locations.tsx
import { mainMap } from "@/content/maps";
import Location from "@/models/Location";
import { navigator, RegisteredLocations } from "@drincs/nqtr";
import { Assets, Sprite, type Texture } from "@drincs/pixi-vn/pixi.js";

export const mcHome = new Location("mc_home", mainMap, {
    name: "MC Home",
    sprite: async (location, { navigate }) => {
        const texture = await Assets.load<Texture>("icon_location_home");
        const icon = new Sprite({
            texture,
            x: 300,
            y: 200,
            height: 120,
            width: 120,
            eventMode: "static",
            cursor: "pointer",
        });
        icon.on("pointerdown", () => {
            const entrance = location.entrance;
            if (entrance) {
                navigator.currentRoom = entrance;
                navigate({ to: "/game/navigation" });
            }
        });
        return icon;
    },
});

RegisteredLocations.add(mcHome);
content/maps.ts
import MapClass from "@/models/Map";
import TimeSlotsImage from "@/models/TimeSlotsImage";
import { RegisteredMaps } from "@drincs/nqtr";

export const mainMap = new MapClass("main_map", {
    name: "Main Map",
    background: new TimeSlotsImage({
        morning: "map-0",
        afternoon: "map-1",
        evening: "map-2",
        night: "map-3",
    }),
    neighboringMaps: {
        north: "nightcity_map",
    },
});

RegisteredMaps.add(mainMap);

Now, before you can use the navigation utilities, you need to set the current room. After that, it is possible to navigate to the navigation screen at the start of the game or after a short initial narrative.

Additionally, it is important to keep in mind that the current location and map are deduced from the current room, so it is sufficient to set the room to obtain all the necessary information for navigation.

You can find more detailed documentation on how to navigate between UI screens here.

For example:

file_type_ink
ink/start.ink
=== start ===
    # navigate /narration
    Hello, welcome to the my first game!

    # enter room mc_room
    # navigate /navigation
    -> DONE

Time system

You can find more detailed documentation about these elements here.

Now let's move on to another fundamental element: the time management system. The time management system is a key component in a Point & Click Adventure, as it allows you to create a dynamic and realistic world where the player's actions can have different consequences depending on the time of day.

The main functionality of the time management system is the ability to advance time based on the player's actions.

file_type_ink
ink/start.ink
// {timeValue} is a number representing the amount of time to increment
// {dateValue} is a number representing the amount of days to increment
# wait {timeValue} // Increment time by {value}
# wait // Increment time by defaultTimeSpent
# wait days {dateValue} // Increment date by {dateValue} and set time to dayStartTime
# wait days {dateValue} hours {timeValue} // Increment date by {dateValue} and time by {timeValue}

Activity

You can find more detailed documentation about these elements here.

A fundamental element in Point & Click Adventures is interactive elements, which allow the player to interact with the environment and progress the story. In NQTR, these elements are represented by activity. activity are elements that can be executed by the player and can have different consequences depending on the context in which they are performed.

For example:

content/activities.tsx
import { ActivityBaseButton } from "@/components/screens/navigation/activity-buttons";
import Activity from "@/models/Activity";
import { RegisteredActivities, timeTracker } from "@drincs/nqtr";
import { narration } from "@drincs/pixi-vn";
import { Bed } from "lucide-react";

export const bed = new Activity(
    "bed",
    async (_, props) => {
        await props.navigate({ to: "/game/narration" });
        if (timeTracker.nowIsBetween(5, 22)) {
            await narration.jump("nap", props);
        } else {
            await narration.jump("sleep", props);
        }
    },
    {
        name: "bed",
        icon: (activity, props) => {
            return (
                <ActivityBaseButton
                    disabled={activity.disabled}
                    onClick={() => activity.run(props)}
                    ariaLabel={props.uiTransition(activity.name)}
                >
                    <Bed className="size-6 sm:size-8 md:size-10 lg:size-12 xl:size-14" />
                </ActivityBaseButton>
            );
        },
    },
);

RegisteredActivities.add(bed);

Activities are connected to rooms in a many-to-many relationship, meaning that an activity can be present in multiple rooms and a room can contain multiple activities.

To use them, you must link them to a room through the activities property. This way, when the player is in that room, they will be able to see the activity and interact with it.

Alternatively, during the narrative session, it is possible to add an activity to a room using the addActivity function.

For example:

== start ==
# add activity bed in mc_room

Routine

You can find more detailed documentation about these elements here.

Routine refers to the set of elements that make up the daily routine of non-player characters (NPC).

The routine is composed of commitment, which represent a character’s obligation to perform a specific activity at a certain moment of the day. These commitments are very similar to activity, as they represent an activity that the character performs.

For example:

content/routine.tsx
import { ActivityBaseButton } from "@/components/screens/navigation/activity-buttons";
import Commitment from "@/models/Commitment";
import { RegisteredCommitments } from "@drincs/nqtr";
import { narration } from "@drincs/pixi-vn";
import { MessageCircleQuestion } from "lucide-react";

export const aliceSleep = new Commitment("alice_sleep", "alice", {
    priority: 1,
    timeSlot: {
        from: 20,
        to: 10,
    },
    background: "alice_roomsleep0A",
    name: "Alice sleeps",
    icon: (commitment, props) => {
        return (
            <ActivityBaseButton
                disabled={commitment.disabled}
                onClick={() => {
                    commitment.run(props);
                }}
                ariaLabel={commitment.name}
            >
                <MessageCircleQuestion className="size-6 sm:size-8 md:size-10 lg:size-12 xl:size-14" />
            </ActivityBaseButton>
        );
    },
    onRun: async (_, props) => {
        await props.navigate({ to: "/game/narration" });
        await narration.jump("talk_alice_sleep", props);
    },
});

RegisteredCommitments.add(aliceSleep);

Commitments are linked to rooms in a one-to-many relationship, meaning that a room can have multiple commitments, but a commitment is present in only one room (a character cannot be in multiple rooms at the same time).

To use them, you need to link them to a room through the commitments property. This will also set the NPC positions, as the position of a commitment is deduced from the room it is linked to. When the player is in that room, they will see the active commitments and be able to interact with them.

Alternatively, during the narrative session, it is possible to add a commitment to a room using the addCommitment function.

For example:

== start ==
# add routine alice_sleep in alice_room

Quests

You can find more detailed documentation about these elements here.

Quest represent an objective or a series of objectives that the player can complete during the game. Quests are composed of stage, which represent the different phases of a quest. Each stage has a specific objective and can be completed in different ways depending on the player's choices.

For example:

content/quests/alice.quest.ts
import { mcRoom, terrace } from "@/content/rooms";
import Quest from "@/models/Quest";
import Stage from "@/models/Stage";
import { RegisteredQuests } from "@drincs/nqtr";

export const aliceQuest = new Quest(
    "aliceQuest",
    [
        // stages
        new Stage("talk_alice1", {
            onStart: () => {
                terrace.addCommitment("alice_quest_talk");
            },
            name: "Talk to Alice",
            description: "Talk to Alice on the terrace",
        }),
        new Stage("order_products", {
            onStart: () => {
                mcRoom.addActivity("order_product");
            },
            name: "Order products",
            description: "Order the products with your PC",
        }),
        new Stage("take_products", {
            onStart: (_, { toast }) => {
                terrace.addActivity("take_product");
                toast("You can take the products on the Terrace");
            },
            name: "Take products",
            description: "Take products on the Terrace",
            requestDescriptionToStart: "Wait for the products you ordered to arrive (2 day)",
            deltaDateRequired: 2,
        }),
        new Stage("talk_alice2", {
            name: "Talk to Alice",
            description: "Talk to Alice on the terrace",
        }),
    ],
    {
        // props
        name: "Help Alice",
        description:
            'To learn more about how the repo works, Talk to Alice. \nGoing when she is there will automatically start an "Event" (see aliceQuest.tsx to learn more). \nAfter that an action will be added to open the pc, in MC room. \n\n(during the quest you can talk to Alice and you will see her talking during the quests of the same Quest)',
        image: "alice_terrace0A",
        onStart: (quest, { toast, uiTransition }) => {
            toast(uiTransition("notify_quest_is_started", { quest: quest.name }));
        },
        onContinue: (stage, { toast, uiTransition }) => {
            toast(uiTransition("notify_quest_is_updated", { quest: stage.name }));
        },
    },
);

RegisteredQuests.add(aliceQuest);

To start a quest, you need to call the start function on the quest itself. This will begin the first stage of the quest, allowing the player to start completing its objectives.

For example:

file_type_ink
ink/start.ink
== start ==
# start quest aliceQuest

To continue a quest that has already been started, you need to call the continue function on the quest itself. This will complete the current stage of the quest and move on to the next one.

For example:

file_type_ink
ink/start.ink
== start ==
# continue quest aliceQuest

During gameplay or narrative sequences, it is very useful to perform checks on the state of a quest, such as verifying whether a quest has been completed or if a specific stage has been reached. To do this, you can use various query functions available in the Quest class, such as completed or failed.

You can find a complete list of query functions in the Quest class documentation here.

For example:

file_type_ink
ink/various_actions.ink
=== talk_alice ===
# show image background alice_terrace0At
{ aliceQuest_currentStageIndex:
- 0: 	-> talk_alice0
- 1: 	-> talk_alice1
- 2: 	-> talk_alice2
- 3: 	-> talk_alice3
- else: alice: Thanks for the book.
}
-> DONE

= talk_alice0
alice: Hi, can you order me a new book from pc?
mc: Ok
alice: Thanks
# continue quest aliceQuest
-> DONE

= talk_alice1
mc: What book do you want me to order?
alice: For me it is the same.
-> DONE

= talk_alice2
mc: I ordered the Book, hope you enjoy it.
alice: Great, when it arrives remember to bring it to me.
-> DONE

= talk_alice3
mc: Here's your book.
alice: Thank you, I can finally read something new.
# continue quest aliceQuest
-> DONE

Conclusion

Now you know the basics for creating a Point & Click Adventure with Pixi’VN and NQTR. So far, we have only looked at the components provided by the template, but it is possible to create custom components to adapt them to the needs of your game. If you have some experience with JS/TS, I’m confident that by modifying the .d.ts files and creating classes that implement NQTR interfaces, you will be able to create custom components quickly and easily.

Make me proud by creating an amazing Point & Click Adventure with Pixi’VN and NQTR! 🚀

Now, you can try a small Point & Click Adventure created with the template to see in practice how the components work and interact with each other.

On this page