Class TimbnQuestBuilder

Namespace

Timbn.GraveyardKeeperTwo.Core.Framework

Assembly

Timbn.GraveyardKeeperTwo.Core.dll

Describes a quest for the plugin's Quests.Add, with who gives it, when it is offered, and what the player does. A quest is a list of stages. What is written on the builder itself (Description, TalksWith, Needs, Talk and the rest) is its first stage, and each AddStage(string, string, Action<TimbnQuestStage>) adds the next, which Core turns into one game quest per stage, each continuing the one before, the way the game builds its own storylines. Every line is the text itself, and Core turns it into localization keys named after the quest id. To keep the text only in the plugin's lang files, use the Quests.Add that takes no name with Description(), Line, and the Accept and Decline that take no text.

public sealed class TimbnQuestBuilder

Inheritance

object

TimbnQuestBuilder

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Examples

Larry wants 3 bottles of wine and pays 300 and a silver bottle for them.

Quests.Add("my_larry_wine", TimbnGameIds.Npcs.Larry, "Larry's Thirst", quest => quest
    .Description("Larry wants 3 bottles of wine.")
    .Offer(talk => talk
        .Say("Could you fetch us 3 bottles of wine?")
        .Accept("Fine.", then => then.Say("Cheers!"))
        .Decline("Not now."))
    .Cost(cost => cost.Item("grape_wine:1", 3))
    .Reward(reward => reward.Money(300).Item("grape_wine:2"))
    .Talk(talk => talk
        .Accept("Here's your wine.", then => then.Say("Lovely."))
        .Decline("Still working on it.")));

Methods

AddStage(string, string, Action<TimbnQuestStage>)

Adds the next stage of the quest, written in the same place. Core makes each stage its own game quest, continuing the one before in the same spot in the quest tree, with the game's own start and complete popups, and each starts by itself once the stage before is done. When the quest itself has stage parts (a Description, a Talk, a ReadyOn and so on), it is the first stage and this one the next. Otherwise the first AddStage is the first stage and keeps the quest's id, and the quest's offer, OfferWhen, StartsOn, OfferAfter and Icon belong to it. Every later stage's id is the quest id plus the stage name. The quest's DoneDescription describes the end of the last stage.

public TimbnQuestBuilder AddStage(string name, string description, Action<TimbnQuestStage> stage)

Parameters

name string

A short name of lowercase letters, digits and underscores. It is part of the stage's id, so keep it stable.

description string

The quest description during this stage.

stage Action<TimbnQuestStage>

Sets up the stage.

Returns

TimbnQuestBuilder

This builder, for chaining.

Examples

Quests.Add("my_gold_wine", TimbnGameIds.Npcs.Larry, "Larry's Gold Wine", quest => quest
    .Offer(talk => talk.Say("Could you find me some gold wine?").Accept("Sure."))
    .AddStage("pay", "Pay Herm for the gold wine.", stage => stage
        .TalksWith(TimbnGameIds.Npcs.Herm)
        .Cost(cost => cost.Money(200))
        .Talk(talk => talk
            .PlayerSay("Larry wants gold wine.")
            .Say("That'll be 2 silver.")
            .Accept("Here's the silver.")
            .Decline("Not now.")))
    .AddStage("deliver", "Bring Larry the gold wine.", stage => stage
        .Cost(cost => cost.Item("grape_wine:3"))
        .Talk(talk => talk.Accept("Here's your wine.")))
    .DoneDescription("Larry got his gold wine."));

ContinuesFrom(TimbnQuest)

Makes the quest the next step of another of your quests, the way the game chains its own quests. It takes that quest's place in the quest tree, sharing its cell, and the tree shows the newest step there. With no Offer or StartsOn of its own, it starts within about a second of that quest being completed, once its OfferWhen is true too if it has one. Only a mod quest can be continued, since a mod never takes a game quest's place.

public TimbnQuestBuilder ContinuesFrom(TimbnQuest quest)

Parameters

quest TimbnQuest

The quest returned by an earlier Quests.Add. For a quest with stages, this continues its last stage.

Returns

TimbnQuestBuilder

This builder, for chaining.

Examples

var ask = Quests.Add("my_wine_ask", TimbnGameIds.Npcs.Larry, "Larry's Wine", quest => ...);
Quests.Add("my_wine_pay", TimbnGameIds.Npcs.Larry, "Paying for the Wine", quest => quest
    .ContinuesFrom(ask)
    .Description("Pay Herm for the wine.")
    ...);

Cost(Action<TimbnCost, TimbnQuestRun>)

A cost read from the quest's run, such as the dish the villager asked for.

public TimbnQuestBuilder Cost(Action<TimbnCost, TimbnQuestRun> cost)

Parameters

cost Action<TimbnCost, TimbnQuestRun>

Adds the cost.

Returns

TimbnQuestBuilder

This builder, for chaining.

Examples

.Cost((cost, run) => cost.Item(run.Item("dish")))

Cost(Action<TimbnCost>)

What the player pays to finish the stage, taken when they pick the talk's Accept answer, which shows it as the game's price and is grayed out until they can pay. The NPC only shows a speech bubble once they can.

public TimbnQuestBuilder Cost(Action<TimbnCost> cost)

Parameters

cost Action<TimbnCost>

Adds the cost.

Returns

TimbnQuestBuilder

This builder, for chaining.

Description()

The quest description with its text only in the plugin's lang files, under quest_open_ plus the quest id plus d while in progress, and quest_closed plus the id plus _d once done. Without the closed line it keeps the in progress one.

public TimbnQuestBuilder Description()

Returns

TimbnQuestBuilder

This builder, for chaining.

Description(string)

The quest description while the quest is in progress.

public TimbnQuestBuilder Description(string text)

Parameters

text string

The text.

Returns

TimbnQuestBuilder

This builder, for chaining.

DoneDescription(string)

The quest description once the quest is done. Left out, it keeps the in progress description.

public TimbnQuestBuilder DoneDescription(string text)

Parameters

text string

The text.

Returns

TimbnQuestBuilder

This builder, for chaining.

DoneLines(Action<TimbnLines>)

Lines that play once a stage with no Talk is done, such as the player thinking aloud on arriving somewhere. Use PlayerSay for those. A Say line comes from the quest giver wherever they stand. A stage with a Talk puts its lines after the Accept answer instead.

public TimbnQuestBuilder DoneLines(Action<TimbnLines> lines)

Parameters

lines Action<TimbnLines>

Adds the lines.

Returns

TimbnQuestBuilder

This builder, for chaining.

Examples

.ReadyOn(TimbnQuestEvent.EnteredWorldZone("vineyard_basement"))
.DoneLines(then => then.PlayerSay("This would be a good place to make wine."))

ExpiresAfter(int)

Cancels a run that has gone this many game days without being finished, whether or not the player took the quest on. The quest goes back to not started and leaves the log, ready for the next NewRun.

public TimbnQuestBuilder ExpiresAfter(int days)

Parameters

days int

Game days from the NewRun, at least 1.

Returns

TimbnQuestBuilder

This builder, for chaining.

Giver(Func<TimbnQuestRun, string>)

The NPC who gives the quest, read from the quest's run, for a quest added with no NPC. The offer's speech bubble shows over them, and the Talk is with them unless TalksWith(string) names someone else.

public TimbnQuestBuilder Giver(Func<TimbnQuestRun, string> npcId)

Parameters

npcId Func<TimbnQuestRun, string>

Picks the NPC from the run.

Returns

TimbnQuestBuilder

This builder, for chaining.

Examples

.Giver(run => run.NpcId("villager"))

Giver(string)

The NPC who gives the quest, for a quest added with no NPC. Use the Func form when the giver changes by run.

public TimbnQuestBuilder Giver(string npcId)

Parameters

npcId string

The NPC, from TimbnGameIds.Npcs.

Returns

TimbnQuestBuilder

This builder, for chaining.

Icon(Func<TimbnQuestRun, string>)

The quest's icon read from its run, such as the icon of the item the villager asked for. Any sprite the game has works, item icons included. Before the first run it shows the icon from Icon(string).

public TimbnQuestBuilder Icon(Func<TimbnQuestRun, string> iconId)

Parameters

iconId Func<TimbnQuestRun, string>

Picks the icon's sprite id from the run.

Returns

TimbnQuestBuilder

This builder, for chaining.

Examples

.Icon(run => TimbnItems.IconId(run.Item("dish")))

Icon(string)

The quest's icon in the quest tree and log, such as quest_icon_larry_portal. Left out, a quest that continues another uses that quest's icon, and any other quest the game's default.

public TimbnQuestBuilder Icon(string iconId)

Parameters

iconId string

The icon's sprite id.

Returns

TimbnQuestBuilder

This builder, for chaining.

Marker(Func<bool>?, Func<bool>?)

Points the player to the NPC to talk to with the HUD's point of interest marker, the one the game uses for work spots. It marks the giver while the offer waits, then whoever takes the hand in once the player can finish, such as the villager waiting on a dish once it is in the bag. While the NPC is off screen the marker sits at the screen edge pointing the way, or on the door that leads to them, and once they are on screen their talk bubble shows instead. Each half can be switched on its own, such as from a setting, and both are read every time the marker updates, so a change applies straight away.

public TimbnQuestBuilder Marker(Func<bool>? offer = null, Func<bool>? handIn = null)

Parameters

offer Func<bool>

Whether the giver is marked while the offer waits, always when left out.

handIn Func<bool>

Whether the NPC taking the hand in is marked once the player can finish, always when left out.

Returns

TimbnQuestBuilder

This builder, for chaining.

Examples

.Marker(offer: () => Settings.IsEnabled(PluginConfig.OfferMarkers), handIn: () => Settings.IsEnabled(PluginConfig.HandInMarkers))

Needs(Action<TimbnNeeds, TimbnQuestRun>)

Needs read from the quest's run, such as having the item the villager asked for.

public TimbnQuestBuilder Needs(Action<TimbnNeeds, TimbnQuestRun> needs)

Parameters

needs Action<TimbnNeeds, TimbnQuestRun>

Adds the needs.

Returns

TimbnQuestBuilder

This builder, for chaining.

Needs(Action<TimbnNeeds>)

What has to be true before the NPC offers the stage's Talk, checked but never taken, such as reputation with that NPC or the day of the week. When the NPC has a menu of its own, the talk's answer shows there with a lock for each until they are met.

public TimbnQuestBuilder Needs(Action<TimbnNeeds> needs)

Parameters

needs Action<TimbnNeeds>

Adds the needs.

Returns

TimbnQuestBuilder

This builder, for chaining.

Offer(Action<TimbnQuestOffer>)

The conversation where the quest giver offers the quest. While the quest can be taken, the giver shows a speech bubble, and talking to them plays this conversation.

public TimbnQuestBuilder Offer(Action<TimbnQuestOffer> talk)

Parameters

talk Action<TimbnQuestOffer>

Scripts the offer. It needs an Accept answer.

Returns

TimbnQuestBuilder

This builder, for chaining.

OfferAfter(string)

Offers the quest only once another quest is completed, and draws it below that quest in the tree with a line from it. Under a game quest it goes right below it, and when that area is full the quests below move down a row to make room.

public TimbnQuestBuilder OfferAfter(string questId)

Parameters

questId string

The id of a mod quest or one of the game's own, such as 58_port_supplies_order.

Returns

TimbnQuestBuilder

This builder, for chaining.

OfferAfter(TimbnQuest)

Offers the quest only once another quest is completed, and draws it below that quest in the tree.

public TimbnQuestBuilder OfferAfter(TimbnQuest quest)

Parameters

quest TimbnQuest

The quest returned by an earlier Quests.Add.

Returns

TimbnQuestBuilder

This builder, for chaining.

OfferWhen(Func<bool>)

An extra condition for offering or starting the quest, such as a story quest having started. An offer is checked about once a second, and a start on a game event is checked when that event happens.

public TimbnQuestBuilder OfferWhen(Func<bool> condition)

Parameters

condition Func<bool>

True when the quest may be offered.

Returns

TimbnQuestBuilder

This builder, for chaining.

OfferWhenExpression(string)

An extra condition for offering or starting the quest, written as one of the game's script expressions, such as IsTechUnlocked("wood_basic") && $money >= 500. It is checked like OfferWhen(Func<bool>).

public TimbnQuestBuilder OfferWhenExpression(string expression)

Parameters

expression string

The game expression, true when the quest may be offered.

Returns

TimbnQuestBuilder

This builder, for chaining.

OnCancel(Action<TimbnQuestRun?>)

Runs your code when a run is canceled, by ExpiresAfter(int), the quest's Cancel or anything else, before the quest goes back to not started, such as taking back something the player was handed. It gets the run, or null for a quest without a Setup, and the quest's Status still says whether the player had taken it on. A throw is logged.

public TimbnQuestBuilder OnCancel(Action<TimbnQuestRun?> action)

Parameters

action Action<TimbnQuestRun>

The code to run.

Returns

TimbnQuestBuilder

This builder, for chaining.

Examples

.OnCancel(run =>
{
    if (parcel.Status == QuestStatus.InProgress && run is not null)
        TimbnItems.TakeFromPlayer(run.Item("parcel"), 1);
})

OnDone(Action)

Runs your code once the stage is done, after the lines that follow the Accept answer, or as soon as they stop if they end early. A throw is logged.

public TimbnQuestBuilder OnDone(Action action)

Parameters

action Action

The code to run.

Returns

TimbnQuestBuilder

This builder, for chaining.

OnDoneExpression(string)

One of the game's script expressions, run once by the game the moment the quest is completed, such as RevealTech("tech_x"). See OnStartExpression(string).

public TimbnQuestBuilder OnDoneExpression(string expression)

Parameters

expression string

The game expression.

Returns

TimbnQuestBuilder

This builder, for chaining.

OnEnd(Action)

Runs your code when the quest stops being in progress, whether it is done, reset, the player leaves the save, or the plugin unloads, to undo what OnStart(Action) did. A throw is logged.

public TimbnQuestBuilder OnEnd(Action action)

Parameters

action Action

The code to run.

Returns

TimbnQuestBuilder

This builder, for chaining.

OnStart(Action)

Runs your code when the quest starts and again whenever a save loads with it in progress. Use it for effects that are not saved, such as a marker or a hold on the player, and undo them in OnEnd(Action). For a change that is saved, use OnStartExpression(string). A throw is logged.

public TimbnQuestBuilder OnStart(Action action)

Parameters

action Action

The code to run.

Returns

TimbnQuestBuilder

This builder, for chaining.

OnStartExpression(string)

One of the game's script expressions, run once by the game the moment the quest starts, such as AddPerk("perk_x") or $money += 50. Use it for changes that are saved, since the save keeps the result. The game also replays a RevealTech("...") here on load. Call it again to add more. A typo fails when the quest is added.

public TimbnQuestBuilder OnStartExpression(string expression)

Parameters

expression string

The game expression.

Returns

TimbnQuestBuilder

This builder, for chaining.

Phase(int)

Which of the game's five rings the quest's node in the quest tree shows while the quest is in progress, the way the game sets one for each of its own quests. The green grows further around with each ring, and a completed quest always shows the gold laurel. Left out, a step of a ContinuesFrom chain gets a ring by its place in the chain, growing as the story goes on like the game's own storylines, and a quest on its own shows the first ring.

public TimbnQuestBuilder Phase(int phase)

Parameters

phase int

The ring, 1 to 5.

Returns

TimbnQuestBuilder

This builder, for chaining.

ReadyByCode()

The quest also waits for your code to call its MarkReady, such as when the player reaches a place.

public TimbnQuestBuilder ReadyByCode()

Returns

TimbnQuestBuilder

This builder, for chaining.

ReadyOn(TimbnQuestEvent)

The quest also waits for something the player does in the game, such as sleeping or crafting.

public TimbnQuestBuilder ReadyOn(TimbnQuestEvent gameEvent)

Parameters

gameEvent TimbnQuestEvent

The event.

Returns

TimbnQuestBuilder

This builder, for chaining.

Repeatable()

Plays the quest again and again. Once its last stage is done, Core puts every stage back to not started and drops it from the quest tree and log until it starts again, so it only ever takes one entry. With a Setup(Func<TimbnQuestRun, bool>) the next play waits for the next NewRun. Without one, the quest is offered again the usual way. No other quest can use OfferAfter or ContinuesFrom on a repeatable quest.

public TimbnQuestBuilder Repeatable()

Returns

TimbnQuestBuilder

This builder, for chaining.

Reward(Action<TimbnRewards, TimbnQuestRun>)

A reward read from the quest's run, such as the sale price of the dish the villager asked for.

public TimbnQuestBuilder Reward(Action<TimbnRewards, TimbnQuestRun> rewards)

Parameters

rewards Action<TimbnRewards, TimbnQuestRun>

Adds the rewards.

Returns

TimbnQuestBuilder

This builder, for chaining.

Examples

.Reward((reward, run) => reward.Money(TimbnItems.SalePrice(run.Item("dish"))))

Reward(Action<TimbnRewards>)

What the player gets when the stage is done. A Talk's Accept answer shows it, and the game pays it when the answer is picked. Otherwise Core pays it when the stage completes.

public TimbnQuestBuilder Reward(Action<TimbnRewards> rewards)

Parameters

rewards Action<TimbnRewards>

Adds the rewards.

Returns

TimbnQuestBuilder

This builder, for chaining.

Setup(Func<TimbnQuestRun, bool>)

Fills a new run of the quest when your code calls the quest's NewRun, such as picking a villager and the dish they want. Until a run is rolled the quest is never offered or started. Text anywhere in the quest shows a run value by its name in braces, such as {dish}, and the overloads of Giver, TalksWith, Needs, Cost and Reward that take a run read it. The run is kept with the save and ends when the quest is done or canceled.

public TimbnQuestBuilder Setup(Func<TimbnQuestRun, bool> setup)

Parameters

setup Func<TimbnQuestRun, bool>

Fills the run. Return false when nothing fits right now, and no run starts.

Returns

TimbnQuestBuilder

This builder, for chaining.

Examples

.Setup(run =>
{
    var villagers = TimbnNpcs.GroupMemberIds(TimbnGameIds.Groups.VillagersDayAll);
    if (villagers.Count == 0)
        return false;

    run.Npc("villager", villagers[UnityEngine.Random.Range(0, villagers.Count)]).Item("dish", "cook_muffin");
    return true;
})

StartsOn(TimbnQuestEvent)

Starts the quest by itself when the player does something in the game, while OfferAfter and OfferWhen allow it.

public TimbnQuestBuilder StartsOn(TimbnQuestEvent gameEvent)

Parameters

gameEvent TimbnQuestEvent

The event.

Returns

TimbnQuestBuilder

This builder, for chaining.

Talk(Action<TimbnQuestTalk>)

The conversation that finishes the stage, with the NPC from TalksWith(string) or the quest giver. Its Accept answer takes the stage's Cost(Action<TimbnCost>), gives its Reward(Action<TimbnRewards>) and completes the stage. Accept with no text completes the stage once the lines are done, for something the NPC simply hands over. See TimbnQuestTalk.

public TimbnQuestBuilder Talk(Action<TimbnQuestTalk> talk)

Parameters

talk Action<TimbnQuestTalk>

Scripts the talk. It needs an Accept.

Returns

TimbnQuestBuilder

This builder, for chaining.

Examples

.Reward(reward => reward.Item("grape_wine:3"))
.Talk(talk => talk
    .PlayerSay("I'm here for my wine.")
    .Say("Found it, here you go.")
    .Accept())

TalksWith(Func<TimbnQuestRun, string>)

The NPC the stage's Talk is with, read from the quest's run, such as the villager a delivery goes to.

public TimbnQuestBuilder TalksWith(Func<TimbnQuestRun, string> npcId)

Parameters

npcId Func<TimbnQuestRun, string>

Picks the NPC from the run.

Returns

TimbnQuestBuilder

This builder, for chaining.

TalksWith(string)

The NPC the stage's Talk is with, such as TimbnGameIds.Npcs.Herm for a job Larry sends the player on. Left out, it is the quest giver.

public TimbnQuestBuilder TalksWith(string npcId)

Parameters

npcId string

The NPC, from TimbnGameIds.Npcs.

Returns

TimbnQuestBuilder

This builder, for chaining.