Drawing

Drawing is an important part of any game. In GM-I18n, you can draw the translated text using the i18n_draw_message() function. It's a wrapper for the draw_text_* functions with convenient additional features, so you can use it just like the draw_text_* functions.

Drawing Presets

Drawing presets are a way to store the drawing configuration so you can use it later. It's optional to use the drawing presets, but it's recommended to use it if you want to draw the translated text consistently.

Before we're creating the drawing presets, you need to create the font assets first. See the Configuration section for more information.

You done creating the font assets? Great! Let's familiarize ourselves with the constructor and most used functions for managing the drawing presets!

Constructor

I18nDrawings

Syntax
I18nDrawings([draw_font], [draw_halign], [draw_valign], [draw_color], [draw_scale], [draw_rotation], [draw_alpha], [text_sep], [text_width])
Description

A constructor for creating a drawing preset. All parameters are optional.

Parameters
NameTypeDefaultDescription
draw_fontFont AssetundefinedThe font to use in draw_set_font() function.
draw_halignHAlignundefinedThe horizontal alignment to use in draw_set_halign() function.
draw_valignVAlignundefinedThe vertical alignment to use in draw_set_valign() function.
draw_colorColor | Color[]undefinedThe color to use in draw_set_color() function, or the color gradient to use in draw_text*_color() function.
draw_scaleRealundefinedThe both scale (x_scale and y_scale) of the text.
draw_rotationRealundefinedThe angle (rotation) of the text.
draw_alphaRealundefinedThe opacity (alpha) of the text.
text_sepReal-1The distance between each line (sep) of the text.
text_widthRealroom_widthThe maximum width (w) of the text.
Returns

I18nDrawings

Examples
// only for explanation purpose, DON'T copy-paste this code
// title
I18nDrawings(fnNotoSans, fa_center, fa_middle, #FFFFFF, 1.2, 0, 1);

// header
I18nDrawings(fnNotoSans, fa_left, fa_middle, #FFFFFF, 1, 0, 1);

// body
I18nDrawings(fnNotoSans, fa_left, fa_top, #CCCCCC, 0.8, 0, 1, 32, 700);

// with other font
I18nDrawings(fnRoboto, fa_right, fa_bottom, #999999, 0.7, 0, 1, -1, 700);

// font asset created from code
I18nDrawings(global.font_ja, fa_left, fa_middle, #FFFFFF, 1, 0, 1);

Functions

i18n_add_drawings

Syntax
i18n_add_drawings(locale, preset_name, data, [use_ref], [i18n]);
Description

Add one or more drawing preset to the selected locale(s).

Parameters
NameTypeDefaultDescription
localeString | String[]The locale code to add the drawing preset(s). You can pass a string for single locale, or an array of string for multiple locales.
preset_nameString | String[]The name of the drawing preset(s). You can pass a string for single preset, or an array of string for multiple presets.
dataI18nDrawings | I18nDrawings[]The drawing preset data. You can pass a single I18nDrawings struct for single preset, or an array of I18nDrawings struct for multiple presets.
use_refBooleantrueUse the first I18nDrawings struct as a reference, instead of creating a new one. Only works if the locale parameter is an array. Recommended to be true if you want to use the same drawing preset for multiple locales.
i18nBoolean | I18nfalseThe I18n struct reference, or leave it empty to use the global i18n struct.
Returns

Void

Examples
Create Event
// add "header" drawing preset to "en" locale
i18n_add_drawings("en", "header", 
    new I18nDrawings(fnNotoSans, fa_left, fa_middle, #FFFFFF, 1, 0, 1)
);

// add "header" drawing preset to "en" and "id" locales
i18n_add_drawings(["en", "id"], "header", [
    new I18nDrawings(fnNotoSans, fa_left, fa_middle, #FFFFFF, 1, 0, 1)
]);

// same, but the "en" and "id" won't have the same struct reference
// only use this if you want to modify the drawing preset for each locale
// otherwise, keep the `use_ref` to `true`
i18n_add_drawings(["en", "id"], "header", [
    new I18nDrawings(fnNotoSans, fa_left, fa_middle, #FFFFFF, 1, 0, 1)
], false);

// add "header" and "body" drawing presets to "ja" locale
i18n_add_drawings("ja", ["header", "body"], [
    new I18nDrawings(global.font_ja, fa_left, fa_middle, #FFFFFF, 1, 0, 1),
    new I18nDrawings(global.font_ja, fa_left, fa_top, #CCCCCC, 0.8, 0, 1, -1, 700)
]);

// add "title", "header", and "body" drawing presets to "en", "id", "my", and "fr" locales
// you're recommended to use this method if you want to use the same drawing preset for multiple locales
// the drawing presets only created once in "en" locale, and the rest of the locale will just reference the "en" locale
i18n_add_drawings(["en", "id", "my", "fr"], ["title", "header", "body"], [
    new I18nDrawings(fnNotoSans, fa_center, fa_middle, #FFFFFF, 1.2, 0, 1),
    new I18nDrawings(fnNotoSans, fa_left, fa_middle, #FFFFFF, 1, 0, 1),
    new I18nDrawings(fnNotoSans, fa_left, fa_top, #CCCCCC, 0.8, 0, 1, -1, 700)
]);

i18n_use_drawing

Syntax
i18n_use_drawing(preset_name, [locale], [i18n]);
Description

Use a drawing preset for the selected locale.

Parameters
NameTypeDefaultDescription
preset_nameStringThe name of the drawing preset to use.
localeString""The locale code to use the drawing preset. Leave it empty to mark it as dynamic locale.
i18nBoolean | I18nfalseThe I18n struct reference, or leave it empty to use the global i18n struct.
Returns

I18nDrawings or Void (if the drawing preset is not found)

Examples
Create Event
// add some drawing presets
i18n_add_drawings(["en", "id"], ["header", "body"], [
    new I18nDrawings(fnNotoSans, fa_left, fa_middle, #FFFFFF, 1, 0, 1),
    new I18nDrawings(fnNotoSans, fa_left, fa_top, #CCCCCC, 0.8, 0, 1, -1, 700)
]);

i18n_add_drawings("ja", ["header", "body"], [
    new I18nDrawings(global.font_ja, fa_left, fa_middle, #FFFFFF, 1, 0, 1),
    new I18nDrawings(global.font_ja, fa_left, fa_top, #CCCCCC, 0.8, 0, 1, -1, 700)
]);
Draw/Draw GUI Event
// use the "header" drawing preset from "en" locale
i18n_use_drawing("header", "en");

// use the "body" drawing preset from "id" locale
i18n_use_drawing("body", "id");

// use the "header" drawing preset from "ja" locale
i18n_use_drawing("header", "ja");

// use the "body" drawing preset for dynamic locale
i18n_use_drawing("body");

Direct Drawing

After you creating the drawing presets, you can use it to draw the translated text. There are two ways to do it:

  1. Using the i18n_draw_message() function. You'll get some benefit from using this function.
  2. Using the i18n_use_drawing() function to change the drawing configuration, and then use the draw_text_* or i18n_draw_message() functions.

What's make the i18n_draw_message() function different from the draw_text_* functions?

  1. Built-in support for the message key. You can pass the message key directly to the function, and it will automatically lookup the message from the locale data, making it a dynamic message without creating any message reference.
  2. Built-in support for the drawing presets. You can easily change the font, color, alignment, etc. by just passing the preset name to the function. See the Drawing Presets section for more information.
  3. Built-in support for the message interpolation and pluralization. Just pass the data to the function, and the function will handle the rest. See the Interpolation section for more information.

Functions

i18n_draw_message

Syntax
i18n_draw_message(x, y, text, [data], [preset_name], [locale], [i18n]);
Description

Draw a normal text or a translated text using the specified drawing preset.

Parameters
NameTypeDefaultDescription
xRealThe x position to draw the text.
yRealThe y position to draw the text.
textStringThe text to draw. You can pass a normal text, or a message key (start with @:) to draw a translated text.
dataInteger | Any[]undefinedThe data to pass to the message pluralization (Integer) or indexed interpolation (Any[]).
preset_nameString""The name of the drawing preset to use. Leave it empty to mark it as dynamic preset.
localeString""The locale code to use the drawing preset (and message key if the text parameter is a message key). Leave it empty if you don't want to use any drawing preset, or you want the message key to be static.
i18nBoolean | I18nfalseThe I18n struct reference, or leave it empty to use the global i18n struct.
Returns

Void

Examples
Create Event
// pluralization
plural_index = 1;

// indexed interpolation
player_name = "John";
intp_data = ["GM-I18n", player_name];
apple = {
    cost : 999999,
    resc : "copper coins"
};

// add some drawing presets
i18n_add_drawings(["en", "id"], ["title", "header", "body"], [
    new I18nDrawings(fnNotoSans, fa_center, fa_middle, #FFFFFF, 1.2, 0, 1),
    new I18nDrawings(fnNotoSans, fa_left, fa_middle, #FFFFFF, 1, 0, 1),
    new I18nDrawings(fnNotoSans, fa_left, fa_top, #CCCCCC, 0.8, 0, 1, -1, 700)
]);

i18n_add_drawings("ja", ["title", "header", "body"], [
    new I18nDrawings(global.font_ja, fa_center, fa_middle, #FFFFFF, 1.2, 0, 1),
    new I18nDrawings(global.font_ja, fa_left, fa_middle, #FFFFFF, 1, 0, 1),
    new I18nDrawings(global.font_ja, fa_left, fa_top, #CCCCCC, 0.8, 0, 1, -1, 700)
]);
Draw/Draw GUI Event
// use the "header" drawing preset from "en" locale
i18n_use_drawing("header", "en");

// and then draw the message
i18n_draw_message(100, 50, "@:hello");          // dynamic message based on "hello" key message
draw_text(100, 50, "Hello, GM-I18n User!");     // static text, the drawing preset still applied

// use `draw_set_*` function if you want
draw_set_font(fnNotoSansBold);
draw_set_halign(fa_right);
draw_set_valign(fa_bottom);
draw_set_color(c_red);
draw_set_alpha(0.5);
i18n_draw_message(100, 50, "@:bye");     // dynamic message based on "bye" key message, but with custom drawing configuration

// draw a dynamic message ("hello" key message) using dynamic "header" drawing preset
i18n_draw_message(100, 50, "@:hello", , "header");

// draw a dynamic message ("bye" key message) using "body" drawing preset on "en" locale
i18n_draw_message(100, 50, "@:bye", , "body", "en");

// draw a static text using the latest drawing preset ("body")
i18n_draw_message(100, 50, "This is a static text");

// draw a static message ("hello" key message) using "title" drawing preset on "ja" locale
i18n_draw_message(100, 50, "@:hello", , "title", "ja");

// draw a static message ("selection" key message) using the latest drawing preset on "id" with static pluralization
i18n_draw_message(100, 50, "@:selection", 0, , "id");

// draw a dynamic message ("selection" key message) using "header" drawing preset with dynamic pluralization based on the `plural_index` value
// bad practice, because the the latest `i18n_draw_message()` function already change the drawing preset to "title"
i18n_draw_message(100, 50, "@:selection", plural_index, "title");

// draw a dynamic message ("welcome" key message) using "body" drawing preset with indexed interpolation based on the `intp_data` value
i18n_draw_message(100, 50, "@:welcome", intp_data, "body");

// draw a static message ("welcome" key message) using the latest drawing preset on "en" with indexed interpolation
i18n_draw_message(100, 50, "@:welcome", [
    "GM-I18n", "Bro"
], , "en");

// draw a dynamic message ("dialog.npc_1" key message) using "header" drawing preset with indexed interpolation
i18n_draw_message(100, 50, "@:dialog.npc_1", [
    apple.cost, apple.resc
], "header");
en.json
{
    "hello": "Hello World!",
    "bye": "Bye World!",
    "selection": "No | Yes",
    "welcome": "Welcome to {0}, {1}!",
    "dialog": {
        "npc_1": "This \"Bad Apple\" is cost {0} {1}!"
    }
}
id.json
{
    "hello": "Halo Dunia!",
    "bye": "Sampai jumpa Dunia!",
    "selection": "Tidak | Ya",
    "welcome": "Selamat datang di {0}, {1}!",
    "dialog": {
        "npc_1": "\"Bad Apple\" ini harganya {0} {1}!"
    }
}
ja.json
{
    "hello": "こんにちは世界！",
    "bye": "さようなら世界！",
    "selection": "いいえ | はい",
    "welcome": "{1}、{0}へようこそ！",
    "dialog": {
        "npc_1": "この\"Bad Apple\"は{0} {1}です！"
    }
}
Currently, the i18n_draw_message() function is the only way to directly draw the translated text in GM-I18n.
The i18n_draw_message() function is not suitable for complex text drawing. For example, you can't use it to draw a text with multiple font size, color, or alignment in a single line.

Don't pass the same preset_name to the i18n_draw_message() function in sequential calls. It will call a redundant i18n_use_drawing() function, which is not efficient.

You can't use named data interpolation with the i18n_draw_message() function. You need to use the i18n_get_messages() or i18n_get_ref_message() function to get the message first, and then pass the message to the i18n_draw_message() or draw_text_* function.
  With this section, you can draw translated texts with consistent style in your game!
Edit this page on GitHub
Table of Contents