Skip to content

Optional Flags

Jump to bottom
Joseph (Drew) Killinger edited this page Mar 30, 2024 · 19 revisions

line_brkr.py Persistent Behaviors

Resetting Newlines

Regardless of length, line_brkr.py will always replace any newlines within a Text Displayable's text with whitespace before inserting new newlines. Furthermore, line_brkr.py will trim any extra unescaped whitespace wherever it exists because "Ren'Py script text collapses adjacent whitespace into a single space character," so any unescaped whitespace will be removed from the text since they are redundant.

For example, entering this command:

python line_brkr.py -r script.rpy -w newscript.rpy

Will run line_brkr.py in its default mode (since no optional flags are given), so this Text Displayable:

show text "  Lorem ipsum\ndolor  \    sit \n amet"
pause

Will look like this after a default run of line_brkr.py.

show text "Lorem ipsum dolor \ sit amet"
pause

Note the absence of any newline characters (\n) and trimming of all whitespace.

Greedy Word Splitting

line_brkr.py will greedily keep your words within your Text Displayable text together if and only if the length of the word doesn't exceed the max length of the text before inserting a line break. In the case that a word exceeds the max text length, it will split the word by newlines as little as possible. For example, entering this command:

python line_brkr.py -r script.rpy -w newscript.rpy -t 2

Will run line_brkr.py with a max text length of 2 character before inserting a newline. So Text Displayable:

show text "Lorem ipsum dolor sit amet"
pause

Will look like this after this run of line_brkr.py:

show text "Lo\nre\nm\nip\nsu\nm\ndo\nlo\nr\nsi\nt\nam\net"
pause

Consequently, doing a default run of line_brkr.py will turn that Text Displayable into this:

show text "Lo re m ip su m do lo r si t am et"
pause

To avoid this behavior, I recommend setting the text length to nothing less than 25 characters, but sometimes your Text Displayable may contain words longer than the max length so consider yourself warned.


Character Length Flags

The Character Length Flags all pertain to setting the desired lengths for many of Ren'Py's potential text values. Not only does Ren'Py allow developers to render text, but developers can also render data, images, and other things within the text as well. Therefore, there are several flags that you can utilize to help line_brkr.py insert newlines into text in a desirable fashion. The following flags are ordered by relevance.

-t or --text-length

"set max length of text (in characters) before breaking line"

The -t or --text-length flag requires one argument; a number. This flag is the bread and butter of line_brkr.py as this flag lets the user set the maximum length of characters that line_brkr.py will allow before it inserts a newline into any desired Text Displayable text. To use this flag properly, the argument provided must be a non-negative whole number (0 -> ∞) else line_brkr.py will raise an Exception.

There are two types of values you can pass into line_brkr.py with the -t flag:

  • 0 (DEFAULT VALUE): passing in 0 with the -t flag tells line_brkr.py that the Text Displayable text should remain unbroken. This means that any newlines within a Text Displayable will be removed.

  • n (where n > 0): passing in n with the -t flag tells line_brkr.py that a newline will be inserted into the Text Displayable text when the text length exceeds n characters.

    For example, entering this command:

    python line_brkr.py -r script.rpy -w newscript.rpy -t 10

    Tells line_brkr.py to begin breaking lines when the line exceeds 20 characters Therefore, this Text Displayable:

    show text "Lorem ipsum\ndolor     sit \n amet"
pause

    Will become this after the program is done running:

    show text "Lorem\nipsum\ndolor sit\namet"
pause

-d or --data-length

"set max length of interpolated data (in characters)"

The -d or --data-length flag requires one argument; a floating-point number. Ren'Py allows developers to Interpolate Data within their text. Because this data can have varying lengths, it is the responsibility of the user of line_brkr.py to specify what that length is. Thus, the -d or --data-length is used to define that length for line_brkr.py. To use this flag properly, the argument provided must be a floating-point number (-1.0 -> ∞) else line_brkr.py will raise an Exception.

There are three types of values you can pass into line_brkr.py with the -d flag:

  • -1: passing in -1 with the -d flag tells line_brkr.py that the Text Displayable data has the same length as the max text length. In other words, every block of interpolated data that line_brkr.py handles will be isolated on its own line.

    For example, entering this command:

    python line_brkr.py -r script.rpy -w newscript.rpy -t 50 -d -1

    Tells line_brkr.py that any interpolated data in any Text Displayable within script.rpy is 50 characters long, and that we want to break text after it exceeds 50 characters. Therefore, this Text Displayable:

    $ data = "dolor"
show text "Lorem ipsum [data] sit amet"
pause

    Will become this after the program is done running:

    $ data = "dolor"
show text "Lorem ipsum\n[data]\nsit amet"
pause

  • 0 (DEFAULT VALUE): passing in 0 with the -d flag tells line_brkr.py that the Text Displayable data has no length. This means that every block of interpolated data that line_brkr.py handles will have a length of 0.

    For example, entering this command:

    python line_brkr.py -r script.rpy -w newscript.rpy -t 25

    Tells line_brkr.py that any interpolated data in any Text Displayable within script.rpy is 0 characters long, and that we want to break text after it exceeds 25 characters. Therefore, this Text Displayable:

    $ data = "dolor"
show text "Lorem ipsum [data] sit amet"
pause

    Will become this after the program is done running:

    $ data = "dolor"
show text "Lorem ipsum [data] sit amet"
pause

  • n (where n > 0.0): passing in n with the -d flag tells line_brkr.py that the Text Displayable data is n characters long.

    For example, entering this command:

    python line_brkr.py -r script.rpy -w newscript.rpy -t 25 -d 10

    Tells line_brkr.py that any interpolated data in any Text Displayable within script.rpy is 10 characters long, and that we want to break text after it exceeds 25 characters. Therefore, this Text Displayable:

    $ data = "dolor"
show text "Lorem ipsum [data] sit amet"
pause

    Will become this after the program is done running:

    $ data = "dolor"
show text "Lorem ipsum [data]\nsit amet"
pause

    Do note that (where m = text length and n = data length) when n < m then the data will be surrounded by other text if possible, else if n > m then all interpolated data will be isolated to its own line.

    In other words, entering this command:

    python line_brkr.py -r script.rpy -w newscript.rpy -t 25 -d 500

    Is effectively the same as entering this command:

    python line_brkr.py -r script.rpy -w newscript.rpy -t 25 -d -1

-i or --image-length

"set max length of in text images (in characters)"

The -i or --image-length flag requires one argument; a floating-point number. Of the many Ren'Py Text Tags, the image tag stands out because it grants the developers the ability to insert a custom image into their text. While this "image should be the height of a single line of text" its width is left undefined. Because this image can have varying widths, it is the responsibility of the user of line_brkr.py to specify what that width is. Thus, the -i or --image-length is used to define that image length for line_brkr.py. To use this flag properly, the argument provided must be a floating-point number (-1.0 -> ∞) else line_brkr.py will raise an Exception.

  • -1: passing in -1 with the -i flag tells line_brkr.py that all Text Displayable image tags have the same length as the max text length. In other words, every image tag that line_brkr.py handles will be isolated on its own line.

    For example, entering this command:

    python line_brkr.py -r script.rpy -w newscript.rpy -t 50 -i -1

    Tells line_brkr.py that any interpolated data in any Text Displayable within script.rpy is 50 characters long, and that we want to break text after it exceeds 50 characters. Therefore, this Text Displayable:

    show text "Lorem ipsum {image=dolor.jpg} sit amet"
pause

    Will become this after the program is done running:

    show text "Lorem ipsum\n{image=dolor.jpg}\nsit amet"
pause

  • 0 (DEFAULT VALUE): passing in 0 with the -d flag tells line_brkr.py that the Text Displayable image has no length. This means that every image tag that line_brkr.py handles will have a length of 0.

    For example, entering this command:

    python line_brkr.py -r script.rpy -w newscript.rpy -t 25

    Tells line_brkr.py that any image tag in any Text Displayable within script.rpy is 0 characters long, and that we want to break text after it exceeds 25 characters. Therefore, this Text Displayable:

    show text "Lorem ipsum {image=dolor.jpg} sit amet"
pause

    Will become this after the program is done running:

    show text "Lorem ipsum {image=dolor.jpg} sit amet"
pause

  • n (where n > 0.0): passing in n with the -d flag tells line_brkr.py that the Text Displayable image tag is n characters long.

    For example, entering this command:

    python line_brkr.py -r script.rpy -w newscript.rpy -t 25 -i 10

    Tells line_brkr.py that any image tag in any Text Displayable within script.rpy is 10 characters long, and that we want to break text after it exceeds 25 characters. Therefore, this Text Displayable:

    show text "Lorem ipsum {image=dolor.jpg} sit amet"
pause

    Will become this after the program is done running:

    show text "Lorem ipsum {image=dolor.jpg}\nsit amet"
pause

    Do note that (where m = text length and n = image length) when n < m then the image tag will be surrounded by other text if possible, else if n > m then all interpolated data will be isolated to its own line.

    In other words, entering this command:

    python line_brkr.py -r script.rpy -w newscript.rpy -t 25 -i 500

    Is effectively the same as entering this command:

    python line_brkr.py -r script.rpy -w newscript.rpy -t 25 -i -1

-s or --space-length

"set max length of space characters (in pixels)"

The -s or --space-length flag requires one argument; a number. Of the many Ren'Py Text Tags, the space tag stands out because it grants the developers the ability to insert whitespace into their text without the need for many escaped space characters ('\ '). However, unlike escaped spaces, the space tag renders white space in pixels not characters. Given how varied the sizes of space characters can be, it is the responsibility of the user of line_brkr.py to specify what that character to pixel ratio is. Thus, the -s or --space-length is used to define how many pixels constitutes a single space character. In other words, space tag value / space length value = # of space characters. For example, a space tag {space=50} with a --space-length of 10 holds 5 characters worth of whitespace (50 / 10 = 5). To use this flag properly, the argument provided must be a floating-point number (-1.0 -> ∞) else line_brkr.py will raise an Exception.

There are two types of values you can pass into line_brkr.py with the -s flag:

  • 0 (DEFAULT VALUE): passing in 0 with the -s flag tells line_brkr.py that the Text Displayable space tag has no character to pixel ratio. This means that any space tag will be left as is.

  • n (where n > 0): passing in n with the -s flag tells line_brkr.py that a single whitespace character is n pixels long.

    For example, entering this command:

    python line_brkr.py -r script.rpy -w newscript.rpy -t 10 -s 10

    Tells line_brkr.py to begin breaking lines when the line exceeds 10 characters, and that single character of whitespace is 10 pixels wide. Therefore, this Text Displayable:

    show text "Lorem ipsum {space=200} dolor sit amet"
pause

    Will become this after the program is done running:

    show text "Lorem\nipsum {space=60}\n{space=100}\n{space=40} dolor\nsit amet"
pause

File Line Flags

Clone this wiki locally