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 it is 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/decimal 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/decimal number. Of the many Ren'Py Text Tags, the image tag stand 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

File Line Flags

Clone this wiki locally