ericoporto / fancy

Script module for fancy text in Adventure Game Studio

fancy

Fancy is a Script module for "fancy" text in Adventure Game Studio.

With Fancy you can have text with multiple colors, fonts, with sprites and other. It brings it's own Typed-Text mechanism and additional fancyness.

The cheatsheet of tags are below. Some tags are "solo", they don't require a closing tag.

• Color tag is "[c:123]" and "[/c]", where "123" is an ags color for the text.
• Outline color tag is "[o:123]" and "[/o]", where "123" is an ags color for the outline.
• Font tag is "[f:123]" and "[/f]", where "123" is an ags font index.
• Sprite tag is solo "[s:123], where "123" is an ags sprite.

Note: use "\n" for linefeed, old lone "[" ags linefeed is not supported.

Notice that if you need to pass a number that is dynamic you can use String.Format to create the string with the proper number, like if the sprite icon you want to put in your text is from a dynamic sprite or the color of a word comes from a character speech color.

Usage

I will improve this soon, for now some small examples

Using a regular drawing surface:

function room_AfterFadeIn()
{
  Fancy.AddAlias("red", 64493); // this should be at game_start

  DrawingSurface* surf = Room.GetDrawingSurfaceForBackground();

  surf.DrawingColor = 10565;
  surf.DrawRectangle(48, 48, 248, 108);
  surf.DrawFancyString(48, 48, "Hello!\n[o:8560]Can you find me the [c:27647]blue cup [s:2041][/c][/o]?\nI lost it in the [c:red]dangerous [f:0]planet[/f][/c], somewhere.", FancyConfig.Create(eFontSpeech, 22422), 200);
}

Simple not-useful typed text example:

FancyTypedText fttb; // has to be global

function room_AfterFadeIn()
{
  Fancy.AddAlias("red", 64493); // this should be at game_start
  Fancy.AddAlias("ico_bcup", 2041); // this should be at game_start

  fttb.FancyConfig.Font = eFontSpeech;
  fttb.FancyConfig.TextColor = 22422;
  fttb.SetDrawingArea(48, 48, 200);
  fttb.Start("Hello!\n[o:8560]Can you find me the [c:27647]blue cup [s:ico_bcup][/c][/o]?\nI lost it in the [c:red]dangerous [f:0]planet[/f][/c], somewhere.");
}

void repeatedly_execute_always()
{
  DrawingSurface* surf = Room.GetDrawingSurfaceForBackground();

  surf.DrawingColor = 10565;
  surf.DrawRectangle(48, 48, 248, 108);

  fttb.Tick();
  fttb.DrawTyped(surf);
}

---

Script API

Script Extensions

DrawingSurface.DrawFancyString

void DrawingSurface.DrawFancyString(int x, int y, const string text, optional FancyConfig* config, optional int width);

Draw the text from a fancy string on the drawing surface.

DynamicSprite.CreateFromFancyString

DynamicSprite* DynamicSprite.CreateFromFancyString(const string text, optional FancyConfig* config, optional width);

Create a sprite with the text of a fancy string

DynamicSprite.CreateFromFancyTextBox

DynamicSprite* DynamicSprite.CreateFromFancyTextBox(const string text, optional FancyConfig* config, optional width, optional Fancy9Piece* f9p);

Create a sprite of a textbox with a fancy string using a 9-piece.

Overlay.CreateFancyTextBox

Overlay* Overlay.CreateFancyTextBox(int x, int y, const string text, optional FancyConfig* config, optional int width, optional Fancy9Piece* f9p );

Creates a screen overlay from a textbox with a fancy string using a 9-piece

Button.Fancify

void Button.Fancify(optional Fancy9Piece* normal, optional Fancy9Piece* mouse_over, optional Fancy9Piece* pushed);

Sets a button NormalGraphic and additional sprites from its text, assumed as fancy string, and 9-piece.

Button.UnFancify

void Button.UnFancify();

Removes fanciness from button (clear any altered sprites)

Fancy

This is a global struct you can't instantiate, it contains static methods for global configuration meant to be used at game start.

Fancy.AddAlias

static void Fancy.AddAlias(String key, int value);

Allows adding a global alias to a tag-value. Ex: AddAlias("red", 63488) allows using [c:red] instead of [c:63488].

This may be useful if you want to be able to change your mind later on what is the specific of a color, or you want to have an easier type remembering sprite icons you are reusing in your texts.

Alias added here are global to all of Fancy. It's recommended that you only add an alias once to everything you need at the game_start of your project, make it easier to manage aliases.

Fancy.FancyConfig

static attribute FancyConfig* Fancy.FancyConfig;

This is the default global FancyConfig, if you don't specify or if you pass null to a method that requires a FancyConfig as parameter it will use this config instead.

Fancy9Piece

This is a managed struct that holds a 9-piece that can be used for drawing text boxes.

Fancy9Piece.CreateFromTextWindowGui

static Fancy9Piece* Fancy9Piece.CreateFromTextWindowGui(GUI* text_window_gui);

Create a 9 piece fancy compatible from a Text Window GUI.

Fancy9Piece.CreateFrom9Sprites

static Fancy9Piece* Fancy9Piece.CreateFrom9Sprites(int top , int bottom, int left, int right, int top_left, int top_right, int bottom_left, int bottom_right, int center_piece = 0, int bg_color = 

0);

Create a 9 piece fancy from 9 sprite slots.

You can optionally pass a color instead of a sprite for the center piece, by passing 0 to center_piece and a valid AGS color in bg_color.

FancyConfig

This is a managed struct meant to configure an instance from FancyTextBase and extensions, prefer using its Create method.

FancyConfig.Create

static FancyConfig* FancyConfig.Create(FontType font, int color, int outline_color, int outline_width, Alignment align, int line_spacing);

Configuration structure for fancy text drawing, allowing customization of font, text color, line spacing, and alignment. By default, when using create, if you don't set, outline color is initially set for COLOR_TRANSPARENT and outline width is initially set to 1, align is set to eAlignBottomLeft and line_spacing is 0.

FancyTextBase

FancyTextBase.SetDrawingArea

void FancyTextBase.SetDrawingArea(int x, int y, int width = FANCY_INFINITE_WIDTH);

Sets the area for drawing fancy text, specifying the position and width.

FancyTextBase.SetFancyText

void FancyTextBase.SetFancyText(String text);

Sets the text content for the fancy text, this is where the parsing of the text happens.

FancyTextBase.Draw

void FancyTextBase.Draw(DrawingSurface* surf);

Draws the fancy text on the specified drawing surface.

FancyTextBase.FancyConfig

attribute FancyConfig* FancyTextBase.FancyConfig;

Property to set the Fancy Text rendering configuration.

FancyTypedText

FancyTypedText.Clear

void FancyTypedText.Clear();

Clears all text and resets everything for typed text.

FancyTypedText.Start

void FancyTypedText.Start(String text);

Sets a new string and resets everything to start typing. You can then use Tick repeatedly to advance the text.

FancyTypedText.Skip

void FancyTypedText.Skip();

Skips all remaining typing of the text.

FancyTypedText.Tick

void FancyTypedText.Tick();

Updates the typed text state, advancing it by a single tick.

FancyTypedText.DrawTyped

void FancyTypedText.DrawTyped(DrawingSurface* surf);

Draws the typed text in its current state.

License

This module is created by eri0o is provided with MIT License, see LICENSE for more details.

fancy's Issues

Write tests for the parser

It would be nice if there was some test for this, just to check I haven't broken anything. I think this may require making the parser function public - but I can hide it from the autocomplete.

I can use the tap module here and similar infrastructure.

Explore a token to reverse text direction

It would be kinda useless now but after we add harfbuzz in ags at least it helps to mix bidirectional text until a native solution is added.

Maybe also let it accept regular

https://www.w3.org/International/questions/qa-bidi-unicode-controls

Add FancySay and FancySayTyped

This would be a nice addition. Need to figure out all the necessary things to make this viable.

FancySayTyped and FancySay wrong behaviors with speech lines

So if a line has a number for speech it will print it on screen. In case of FancySayTyped it will also say the line twice. Need to fix both cases...

Verify anti alias text is working with semi transparent bg

The Speech Bubble module had this workaround for anti aliased strings that were draw in semi transparent backgrounds

https://github.com/messengerbag/SpeechBubble/blob/1c0d6df7c4968f24665b05b9c4e53f4df3e72376/SpeechBubble.asc#L848

In this module we render all the text and later draw it on top of the 9 piece textbox in the background - which should blend and not blit it.

Need to check if this works for the case where the font has anti alias and the background is semi transparent or we need some workaround. One possible source of issue would be with outlines.

But it's possible that the way we work things is alright too.

Refactor to reduce code duplication

The "pipeline" of parsing tokens and such before drawing is defined multiple times. It should instead be on defined in one place (function?) and reused throughout the module.

Adjust to instead use it's own overlay

https://www.adventuregamestudio.co.uk/forums/modules-plugins-tools/module-fancy-0-1-0/msg636662896/#msg636662896

Read X, Y and ZOrder from the text overlay and adjust a new overlay to use to avoid the x and y bugs in ags3.

Better test demo

We probably want something with higher resolution, to test performance, and something where all the API is used so it's easier to check for problems.

Vertical top to bottom text

I have no idea how it would work but perhaps someone at some point pass around here and give an idea or I get some lightning strike in the shower.

Anyway, I don't think I will be able to come up with a token-wise approach for this, but what I could have is some alternative filter that sets the tokens width and height assuming they are top to bottom and have a draw tokens function that understands drawing vertical text.

Probably need to figure some word-wrapping for vertical text too.

Additionally I also need to add height since it will need some height limit for word-wrapping.

Sync the markdown readme to the bbcode one

I mostly care about the bbcode readme because of the forums, but need to sync the one here because I use it sometimes when the forums are down.

Add something for text boxes from 9-piece images

No idea yet how it would work, but essentially being able to create a sprite from text and a 9-piece and work from there.