Stendhal Quest Coding - Part 3

From Arianne
Jump to: navigation, search



Stendhal Quests

You may want to read the first part and second part of the Stendhal Quest Coding tutorial first.

If you have ideas for new quests or are interested in helping to refine quest ideas, please have a look at the Quest Contributor's Guide or the Stendhal Quest Ideas.


Rewarding the player

In the last section of this tutorial we taught Hayunn to only accept one beer per player. We didn't actually take the beer from the player nor did we reward the player. We want to add this functionality now.

We have to do several things at once:

  • take the beer from the player
  • provide some money as refund
  • increase the xp and karma
  • and finally remember that the quest was completed

But don't worry, that sounds more complicated than it actually is. There are already actions for all of these tasks that can be combined using a MultipleAction:

    List<ChatAction> reward = new LinkedList<ChatAction>();
    reward.add(new DropItemAction("beer"));
    reward.add(new EquipItemAction("money", 20));
    reward.add(new IncreaseXPAction(50));
    reward.add(new IncreaseKarmaAction(10));
    reward.add(new SetQuestAction(QUEST_SLOT, "done"));
    npc.add(
         ConversationStates.ATTENDING,
         "beer",
         new PlayerHasItemWithHimCondition("beer"),
         ConversationStates.ATTENDING,
         "*glug glug* Ah! That hit the spot. Let me know if you need anything, ok?",
         new MultipleActions(reward));

Asking the player for the beer

Let's make it a bit easier for player to remember that they bought a beer in order to give it to Hayunn. Hayunn should notice the beer as soon as the player says "hi" and he actively asks for it.

Therefore we add a new trigger for the GREETING_MESSAGE. There is an internal rule that transitions which have a condition (that is true) are preferred over equal transitions without one. So our greeting transition is used instead of the normal one if the player has the item and the quest is active. Similar to the MultipleAction, there is an AndCondition which combines multiple elementary ones.

    // player has the quest active and has a beer with him, ask for it
    npc.add(
        ConversationStates.IDLE,
        ConversationPhrases.GREETING_MESSAGES,
        new AndCondition(new QuestActiveCondition(QUEST_SLOT), new PlayerHasItemWithHimCondition("beer")),
        ConversationStates.QUEST_ITEM_BROUGHT, 
        "Hey! Is that beer for me?",
        null);

    // player has accepted the quest but did not bring a beer, remind him
    npc.add(
        ConversationStates.IDLE,
        ConversationPhrases.GREETING_MESSAGES,
        new AndCondition(new QuestActiveCondition(QUEST_SLOT), new NotCondition(new PlayerHasItemWithHimCondition("beer"))),
        ConversationStates.ATTENDING, 
        "Hey, I'm still waiting for that beer, remember? Anyway, what can I do for you?",
        null);

As we have learned in the second part of this tutorial, we use a new state for the question. In this case it is named QUEST_ITEM_BROUGHT.

Important note: You need to check again that the player still has the beer when he says yes. Otherwise he could have dropped it to the ground after Hayunn saw it and went to state QUEST_ITEM_BROUGHT.

    // okay, the player wants to give us a beer :-)
    List<ChatAction> reward = new LinkedList<ChatAction>();
    reward.add(new DropItemAction("beer"));
    reward.add(new EquipItemAction("money", 20));
    reward.add(new IncreaseXPAction(50));
    reward.add(new IncreaseKarmaAction(10));
    reward.add(new SetQuestAction(QUEST_SLOT, "done"));
    npc.add(
         ConversationStates.QUEST_ITEM_BROUGHT,
         ConversationPhrases.YES_MESSAGES,
         new PlayerHasItemWithHimCondition("beer"),
         ConversationStates.ATTENDING,
         "*glug glug* Ah! That hit the spot. Let me know if you need anything, ok?",
         new MultipleActions(reward));

    // the player has a beer but wants to keep it for himself :-(
    npc.add(
        ConversationStates.QUEST_ITEM_BROUGHT,
        ConversationPhrases.NO_MESSAGES,
        null,
        ConversationStates.ATTENDING,
        "Drat! You remembered that I asked you for one, right? I could really use it right now.",
        null);

Quest Documentation

We are almost done now. Almost? Yes, a very important thing is still missing. And we should have done it as the first thing. But well, better late than never. Here we create the javadoc which summarises our code in a readable form, for other developers and for our future selves!

/**
 * QUEST: Beer For Hayunn
 * 
 * PARTICIPANTS:
 * <ul>
 * <li>Hayunn Naratha (the veteran warrior in Semos)</li>
 * <li>Margaret (the tavern maid)</li>
 * </ul>
 * 
 * STEPS:
 * <ul>
 * <li>Hayunn asks you to buy a beer from Margaret.</li>
 * <li>Margaret sells you a beer.</li>
 * <li>Hayunn sees your beer, asks for it and then thanks you.</li>
 * </ul>
 * 
 * REWARD:
 * <ul>
 * <li>20 gold coins</li>
 * <li>50 XP</li>
 * <li>10 karma</li>
 * </ul>
 * 
 * REPETITIONS:
 * <ul>
 * <li>None</li>
 * </ul>
 */

This documentation is only a little work in most cases because it is just a reformatted version of the quest description.

Quest Information Methods

These are used for the travel logs and other parts of the game which refer to quests - e.g. the achievement for completing all quests in Semos needs the region to be set for quests in Semos city, to be able to find them. These standard methods give meta information about the quest which is accessible to other parts of the Stendhal code.

getHistory

This fills in the quest history in the travel log. It is basically a list of steps in the quest in readable form. It starts with an empty list and then checks the state of the player. The list is added to if the player has completed that step. Finally the list is returned at the end.

    @Override
    public List<String> getHistory(final Player player) {
        final List<String> res = new ArrayList<String>();
	if (!player.hasQuest(QUEST_SLOT)) {
	    return res;
	}
	res.add("I have talked to Hayunn.");
	final String questState = player.getQuest(QUEST_SLOT);
	if ("rejected".equals(questState)) {
	    res.add("I do not want to make Hayunn drunk.");
	}
	if (player.isQuestInState(QUEST_SLOT, "start", "done")) {
	    res.add("I promised to buy him a bear from Margaret in Semos Tavern.");
	}
	if (("start".equals(questState) && player.isEquipped("beer")) || "done".equals(questState)) {
	    res.add("I have a bottle of beer.");
	}
	if ("done".equals(questState)) {
	    res.add("I gave the beer to Hayunn. He paid me 20 gold coins and I got some experience.");
	}
	return res;
    }

There are a few ways to check the states. Some developers use ChatConditions like we did when setting the NPC conversation. Others use more direct checks on the quest state. If using ChatConditions, these have been written to work with the add method for the NPC. If you just want to use them to get a true/false value directly, , you need to get at the 'fire', for example (new() QuestCompletedCondition(QUEST_SLOT).fire(player, null, null).

getQuestInfo / fillQuestInfo

TODO: populate with an example from BeerForHayunn and explanation

getMinLevel

This piece of meta information suggests the minimum level of player who may be expected to completed the quest. It's not a hard requirement - ChatConditions on the level should be used if you really want to add a level restriction, when the NPC offers the quest.

This value is used in the travel log and for other NPCs who might hint that you start unstarted quests - they won't hint at unstarted quests beyond your level. If the value is 0, i.e. any player can do it, you don't need to add this method, as this is the default (though, BeerForHayunn does explicitly set the value to 0 and there is no harm in this.)

@Override
public int getMinLevel() {
    return 10;
}

getRegion

If there is a specific region matching one of the Stendhal regions, as defined in Region.java, then you can set this here and any achievements or NPCs referring to quests from that region will notice the quest. You can leave this method out if you have no region to set (e.g. global quests) because the default is null.

@Override
public String getRegion() {
    return Region.SEMOS_CITY;
}

getNPCName

Fill in the name of the NPC that the player starts the quest with. You can leave this method out if there is no specific NPC who starts the quest (e.g. the Seven Cherubim quest where you just start meeting any of the angels.) This is unlikely to happen often.

@Override
public String getNPCName() {
    return "Hayunn Naratha";
}

Reference functions that gather 'meta' information about the quest use this - for example if an NPC wants to list which NPCs to speak to to start quests in a certain region.


TODO: Others? isCompleted? isRepeatable? More of the name ones?

Further Reading and Complete Code

You can have a look at the complete source code for this quest.

The pages might be of interest to you: