Harlowe Create Custom Macro

MIster jashon

5 min read

·

Oct 04, 2024

27

Share

Harlowe: Crafting Your Own Macros for Storytelling Power

Harlowe, the scripting language within ChoiceScript, is a powerful tool for interactive fiction writers. While it offers a wide range of built-in commands, sometimes you need a bit more customization to bring your unique vision to life. This is where custom macros come in.

What are Custom Macros?

Imagine custom macros as your own personalized shortcuts within Harlowe. They allow you to encapsulate a set of actions or logic into a single, reusable command. This means you can:

• Simplify Complex Tasks: Instead of writing repetitive lines of code, a macro can condense those instructions into a single command.
• Enhance Readability: Macros can make your Harlowe code clearer by giving descriptive names to common actions.
• Promote Reusability: Once you create a macro, you can use it multiple times throughout your story, saving time and effort.

Building Your First Macro

Let's create a simple macro to display a character's name and a message:

// Define the macro
create macro speak(character, message) {
  "[[character]] says: [[message]]";
}

// Use the macro
<> 

Explanation:

1. create macro speak(character, message): This line defines the macro named "speak". It takes two parameters: character and message.

2. "[[character]] says: [[message]]": This is the code that will be executed when the macro is called. [[character]] and [[message]] will be replaced with the actual character name and message provided when you call the macro.

3. <<speak("Alice", "Hello there!")>>: This is how you use the macro. "Alice" and "Hello there!" are passed as the values for character and message respectively.

Going Deeper with Macros

Harlowe macros can handle more advanced tasks. Here's an example of a macro that checks a character's health and displays a message accordingly:

create macro checkHealth(character) {
  if (character.health > 70) {
    "[[character]] is feeling great!"
  } else if (character.health > 30) {
    "[[character]] is a bit weary."
  } else {
    "[[character]] needs some rest!"
  }
}

<>

Key Points to Remember:

• Scope: Macros are defined within the current passage. If you need a macro accessible from all passages, define it in a separate "macros" passage.
• Parameter Types: Macros can accept parameters of various types: strings, numbers, objects, or even other macros.
• Return Values: Macros can return values (like a string or a number) using the return keyword.

Example: Customizing Interactions

Let's say you want to create a custom interaction system where players can choose to "talk", "fight", or "run" when encountering a character. Here's how you might structure it using macros:

// Define the interaction macros
create macro talk(character) {
  "You decide to engage [[character]] in conversation..."
}

create macro fight(character) {
  "You charge into battle against [[character]]!"
}

create macro run(character) {
  "You flee from [[character]]!"
}

// Example usage in a passage
You encounter a menacing goblin.  What do you do?
<> [[talk("goblin")]] <>
<> [[fight("goblin")]] <>
<> [[run("goblin")]] <>

Conclusion:

Custom macros in Harlowe are a powerful tool for streamlining your code and creating truly unique storytelling experiences. By taking the time to learn and leverage this feature, you can unlock a new level of expressiveness and efficiency in your interactive fiction projects.