EZ Text Replacer for Zelda64Recompiled 2.2.0
 
All Data Structures Files Functions Typedefs Enumerations Macros Modules Pages
Loading...
Searching...
No Matches
EZ Text Replacer for Zelda64Recompiled

EZTR is a complete in-game text, message, and dialog suite for Zelda64Recompiled modding. With it, you can:

  • Replace any vanilla game dialog, item description, or other on-screen message.
  • Add your own brand-new message entries for custom NPCs.
  • Dynamically generate message content at runtime, using callbacks.

And more!

Basic Replacements

Replacing dialog is straightforward.

In your mod code, create a function with the following signature:

// This function can be named whatever you want.
EZTR_ON_INIT void my_initialization_function() { ... }
#define EZTR_ON_INIT
Used to declare a function that should run after EZTR has finished initializing.
Definition eztr_api.h:258

Inside this function, you will define each text replacement you want to make using EZTR's Basic_Replacement API. For example:

#include "eztr_api.h"
EZTR_ON_INIT void init_text() {
0x061B,
EZTR_STANDARD_TEXT_BOX_I,
0,
EZTR_ICON_NO_ICON,
false,
"Hey, apprentice! Don't just stand" EZTR_CC_NEWLINE "around lookin' at the sky all" EZTR_CC_NEWLINE "day!" EZTR_CC_EVENT2 EZTR_CC_END,
NULL
);
}
The main header for EZTR.
#define EZTR_NO_VALUE
Used by certain members of EZTR_MsgData (and the message header generally) to indicate that said memb...
Definition eztr_api.h:304
void EZTR_Basic_ReplaceText(u16 textId, u8 text_box_type, u8 text_box_y_pos, u8 display_icon, u16 next_message_id, u16 first_item_rupees, u16 second_item_rupees, bool pipe_escape_bytes, char *content, EZTR_MsgCallback callback,...)
Declare a replacement of a vanilla message by defining the header attributes and message content.
#define EZTR_CC_EVENT2
End Conversation.
Definition eztr_api.h:1209
#define EZTR_CC_NEWLINE
Line Break.
Definition eztr_api.h:797
#define EZTR_CC_END
Message End Marker.
Definition eztr_api.h:1034

Messages can also be dynamically generated at runtime based on code. For example:

// Callback used to set Bomb Shop owner dialog.
EZTR_MSG_CALLBACK(bombshop_nonhuman_callback) {
Player* player = GET_PLAYER(play);
if (player->transformation != PLAYER_FORM_DEKU) {
buf->data.text_box_type = EZTR_STANDARD_TEXT_BOX_II;
EZTR_MsgSContent_Sprintf(buf->data.content, "...Welcome." EZTR_CC_EVENT EZTR_CC_END);
} else {
// Vanilla Dialogue:
EZTR_MsgSContent_Sprintf(buf->data.content, "You can't use any of them, but" EZTR_CC_NEWLINE "feel free to look around." EZTR_CC_EVENT EZTR_CC_END);
}
}
EZTR_ON_INIT void init_text() {
// Replacements for Bomb Shop
0x064B,
EZTR_STANDARD_TEXT_BOX_I,
0,
EZTR_ICON_NO_ICON,
false,
"\xBF",
bombshop_nonhuman_callback
);
}
#define EZTR_MSG_CALLBACK(fname)
A macro to easily create message callback functions.
Definition eztr_api.h:243
#define EZTR_CC_EVENT
Disable Text Skip II.
Definition eztr_api.h:862
int EZTR_MsgSContent_Sprintf(char *buffer, const char *format,...)
A modified version of printf, specially designed to handle message content. This version uses pipe-es...

See Message Buffers and Callbacks to learn more.

You can add custom messages through a similar process. For example:

EZTR_DEFINE_CUSTOM_MSG_HANDLE(my_custom_message_handle);
EZTR_ON_INIT void init_text() {
EZTR_HNAME(external_custom_message_handle),
EZTR_STANDARD_TEXT_BOX_I,
0,
EZTR_ICON_NO_ICON,
false,
"HELLO WORLD AGAIN!!\xBF",
NULL
);
}
void EZTR_Basic_AddCustomText(EZTR_CustomMsgHandle handle, u8 text_box_type, u8 text_box_y_pos, u8 display_icon, u16 next_message_id, u16 first_item_rupees, u16 second_item_rupees, bool pipe_escape_bytes, char *content, EZTR_MsgCallback callback,...)
Declare a brand new (i.e: custom) message by defining the header attributes and message content.
#define EZTR_DEFINE_CUSTOM_MSG_HANDLE(name)
Creates a CustomMsgHandle object.
Definition eztr_api.h:150
#define EZTR_HNAME(name_suffix)
Shorthand for EZTR_CUSTOM_MSG_HANDLE_NAME()
Definition eztr_api.h:200

Check out the Custom Messages and Handles page to learn more.

Dumping Messages

To easily access the raw message data needed for replacements, go to EZTR's configuration page and enable Text Dumping.

./eztr_config_page.png

When enabled, EZTR prints message data to the Zelda64Recompiled console whenever a message is loaded/displayed. There are also a couple of formatting options provided:

  • Dump Text as C Code - When enabled, text dumps will be formatted as calls to EZTR’s text-replacement API.
  • Text Dumping Byte Format - How non-printable bytes are dumped, with _ representing hexadecimal digits. See the section on pipe-escaped bytes for information on the Pipes option.
  • Print the EZTR control code macro from Control_Code_Macros (when available) when dumping a non-printable byte.

Additionally, you may want to check out the EZTR Dump To Disk Extension, which can generate a preformatted C file with all the messages you've dumped.

More Information

The complete eztr_api.h header is documented on this site. For more information, visit the various topic pages for each part of the API:

  • General - General API Information
  • CustomMsgHandle - Macros and types used for working with the handles for custom messages.
  • Types - Type definitions that EZTR uses for Majora's Mask messages.
  • Control_Code_Macros - Macros for the various control codes and non-printable bytes used in the Majora's Mask text encoding.
  • Basic_Replacement - Functions for replacing vanilla messages.
  • Basic_CustomMessages - Functions for creating and replacing new messages.
  • MsgBuffer - Functions for high-level message buffer operations.
  • MsgSContent - Functions for manipulating message text content.