pau-tomas / gb-studio-plugins

A set of experimental plugins for GB Studio

GB Studio 3.2 - Plugin Pak

A set of experimental plugins for GB Studio 3.2. Use them at your own risk :)

Dialogue & Menus

Display Advanced Dialogue

Show a dialogue box at the bottom of the game screen.

The Text tab behaves exactly like the Display Dialogue event.

The Layout tab allows to configure multiple options for the dialogue box:

• Minimum and maximum height of the display box, and if the border should be rendered or not.
• The starting position of the text.
• The maxmimum number of lines before the text will start scrolling up.
• Configure when the dialogue will close:
  • When a button is pressed
  • When the text finishes rendering
  • Never (the dialogue box will remain on screen and allow other interactions. The dialogue can be hidden using the Hide Overlay or Overlay Move To events).
• If the previous content should be removed when displaying the dialogue. This is useful to avoid the text flickering when dialogue boxes are open with Instant speed.
• If the dialogue should render at the bottom or the top of the screen. (Note: Pay attention to the warnings on the event when using top position)

Display Advanced Menu

Display a menu of multiple options and set the specified variable to the value of the chosen option.

Menu option position and navigation order can be set for each item in the Items tab. The dialogue box size and the opening and closing direction can be set in the Layout tab.

There's no maximum character length per item, but the total amount of displayed characters is limited to by the number of tiles reserved for UI text (52 for non-color mode).

Note: The event can get very long when there's a lot of items.

Display Background Text

Renders a line of text at a specified position in the scene background.

There's no maximum character length for the text, but the total amount of displayed characters in a scene is limited to by the number of tiles reserved for UI text (52 for non-color mode), this includes text displayed with this event but also any other dialogue or menu.

Unfortunately, autocomplete of variables isn't available for single line textboxes in plugins. Use $xxx$ to render a variable as part of the text, for example $100 to render the value of Variable 100.

Printer

Note: The embedded GB Studio emulator doesn't have support for printing, this event will always fail when tested there. Use a real device or an emulator with printer support.

Print Screen Background

Prints the visible background of the current scene using GB Printer. In Color Mode the CPU will be set to Single-speed mode while the event is running.

• On Error: A script to run if there's an error when trying to print.

Real Time Clock

A set of events that give access to the Real Time Clock functionality present in some GB cartridges.

Note: Cartridge type needs to be set to MBC3 in the project Settings, for RTC to work.

Set Clock Time

Set the values of the real time clock fields with a number or the value of a variable.

Store Clock Time In Variables

Store the current time in one variable for each value.

Start Clock

Starts the real time clock.

Stop Clock

Stops the real time clock.

Music & Sound Effects

Mute Channel

Mutes one or more channels for the currently playing music.

Player Fields

Store Player Field In Variable

Store the value of a Player Field in a variable.

The available fields are:

• Platformer scenes:
  • Player Velocity X: Current horizontal velocity for the player.
  • Player Velocity Y: Current vertical (jumping) velocity for the player.
  • Player is in the ground: 1 if the player is jumping or 0 if it's not.
  • Player is on ladder: 0 if the player is on a ladder or 1 if it's not.

Player Field Update

Change the value of a Player Field.

The available fields are:

• Platformer scenes:
  • Player Velocity X: Current horizontal velocity for the player.
  • Player Velocity Y: Current vertical (jumping) velocity for the player.

Camera

Store Camera Field In Variable

Store the value of a Camera Field in a variable.

The available fields are:

• Camera X: Current horizontal camera position.
• Camera Y: Current vertical camera position.
• Scroll X: Current horizontal scroll position.
• Scroll Y: Current vertical scroll position.
• Camera Deadzone X: Current horizontal edge for the camera window.
• Camera Deadzone Y: Current vertical edge for the camera window.
• Camera Offset X: Current horizontal camera position relative to the edge of the screen.
• Camera Offset Y: Current vertical camera position relative to the edge of the screen.

Camera Field Update

Change the value of a Camera Field.

The available fields are:

• Camera Deadzone X: Current horizontal edge for the camera window.
• Camera Deadzone Y: Current vertical edge for the camera window.
• Camera Offset X: Current horizontal camera position relative to the edge of the screen.
• Camera Offset Y: Current vertical camera position relative to the edge of the screen.

Screen

Smooth Fade

Color Mode Only

Fade some or all of the current scene's background or sprites palettes to or from a white or black screen, interpolating the color values for a smooth fade.

β Plugins

The plugins in this category are even more experimental than the ones above and might change in the future.

• Move Variable Actor To and Store Variable Actor Position In Variables:
  • These events duplicate existing GB Studio Actor events but instead of using a dropdown to select the actor they use a variable. The value of the variable represents the index of the actor in the scene (the player is always 0 and the rest of the actors have an index assigned based on when they were added to the scene).
• Actor FX:
  • Run visual effects on an actor. Currently only Split In / Split Out effects are implemented. More to come (maybe?).
• Locked Event Group and Unlocked Event Group:
  • Lock or unlock the executuon of parts of your script. A locked script doesn't allow other scripts to run in parallel.
• Pin Actor to Screen and Unpin Actor from Screen:
  • Pin or Unpin the actor to its current screen coordinates. Be aware of the current state of the actor: If it's already pinned or unpinned when the event is called its position will be wrongly offset based on the scroll position.

How to Install

Drop the plugins folder in your project. All the above events will be available from the Add Event button.

Looking for more plugins?

• NalaFala (Yousurname)'s GB Studio Plugin Collection
• Platformer+
• Advanced Dialog and Menu vB
• Shin's GB Studio plugins

gb-studio-plugins's Issues

Display background text plugin doesn't output variable values

If I use $variable in the Display background text plugin it doesn't output that variable in the text, I thought it would but it doesn't

Mute Channel Not Muting Channel

I am using Mute Channel and it is not affecting music at all. I have tried using the event both before and after starting music.

Advanced Dialogue: Non-Modal Dialogue pinned to top causes screen flicker

Hello,

Summarizing this issue here for you after troubleshooting on the discord.

I have a platformer scene with advanced dialogue being used to create a HUD. It is pinned to the top of the screen, and does not clear. It is only updated once at the beginning of a scene init, and then refreshed again if a coin is collected, but there is no constant updating via timer/on update/etc.

When pinning the dialogue to the top, there is a screen flicker on the left hand side of the screen:
https://user-images.githubusercontent.com/65201358/209164170-778a6c3e-2e53-48df-8835-6ba70f2c07da.mov

This does not occur when the dialogue events are pinned to the bottom.

Oddly, this is not present during emulation. It's only there when testing on the Gameboy Pocket. Notably, it did not occur when inserting the same cart into my GBA. I can't 100% rule out that it's not a hardware problem, but perhaps its not on the GBA or emulation due to the differences in tech?

Display Background Text does not work past certain distances

I have a scene larger than 160x144. By extending the max ranges in the plugin, I can draw text in the background up until ~Y32 (original max was Y17). However, when moving a 3rd screen distance vertically, the draw background text event does not write anything in the new view (Y48).

nice plugin!

hi im in gbstudio 3.1.0 plugin options are nice.
I found though using the background text makes the advance dialog text not show? Also the advance dialog is set to never go away, but it goes away when i interact with npc? lastly, once i set and start clock, how can i see it?
is there a variable to put in dialog to see the numbers? Could this work as a countdown/stopwatch? thanks!

Printer Plugin: Sibling Events of a Print Screen Background don't fire when attached to a Button

When you attach the 'Print screen background' Event to a button ('Attach Script to Button'), other events coming before or after it don't get executed.
For my example, I wanted to show an Actor (showing a 'printing…') graphic, when you start printing.
The way I initially tried to do this, was by setting this chain of events in the button script:

• Show Actor
• Print Screen Background
• Attach timer script (3s)
  • Hides the Actor
  • remove timer script

But no Events fired except the 'Print'.

I worked around this by putting the 'Print Screen Background' Event inside its own timer:

• Show Actor
• Attach timer script after 1 frame
  • Hide Actor
  • Remove timer script
  • Print Screen Background

But ideally, all sibling Events of 'Print' should fire, when they are attached directly to a Button

No description for smooth fade

I’m wondering what it does

Advanced Dialogue: Can't reset scanline after using Top dialogue

I'm trying to follow the guidelines for resetting the dialogue placement after using a non-modal top rendered advanced dialogue.

However, any non-top dialogue is invisible after using the top dialogue and trying to clear as above. Is this not the correct method to reset according to the tip provided in the event? Is it a bug, or am I misunderstanding its usage?

Display background text cannot use different fonts

I tried to change the font of the background text using the "!f" command, but it didn't work.

Display Background Text overflows into tiles that have been previously written into

It looks like there's no limit on the amount of space that Display Background Text can fill. So if you have a large continuous string of white tiles, the text-writing routine goes hogwild and fills as much as it can.
Edit: This large overfill issue was happening because I had used the same background in a "logo" scene.

Requesting a "length" field or width/height fields, and an option to clear tiles before writing. 🙏

This doesn't happen as severely when background tiles are present, but it does still affect tiles previously filled with text.

Steps to reproduce:
GB Studio 3.0.3
Create a new scene, use any background.
Create an actor, and add the following events to On Init:

Player Fields onGound variable hanging for a bit before beginning to update.

Running into an issue with the Player Fields plugin.

Currently have a test project set up to fire a bullet when the player is in the air, as well as report the status of the "onGound" Bool when start is pressed. As you can see in the attached gif, for the first minute or so, the variable doesn't update, constantly reporting 0 when start is pressed regardless of player status, and fires bullets constantly.

After ~ a minute, it suddenly starts working as expected, the variable updates when checked, and bullets only fire in the air.

On 3.02, on macOS Monterey.

Kernel panic occurred with the Printer plugin on GB Studio 3.1.0

Hello, I had a kernel panic error occur with the Printer plugin on GB Studio 3.1.0.

This was tested on a Game Boy with the GB Printer as well as in the mGBA emulator with the printer emulation.

Here is the the test project with a .gb build that I used with the plugin when I got the kernel panic error.

gbprintertest.zip

Printer mode not working when compiled as a Color project

I've noticed that an error is displayed when printing as soon as I compile in Gameboy Color mode on GB Studio. The same project prints without any problems when compiled in classic mode. Is it possible to have the printer plugin working in color mode or is this a limitation at the hardware level?

I can provide a sample project if needed.

Feature request: printer 'on success' event

Since there is an error event, is it possible to also add a 'success' or 'done' event? That would enable devs to put up a 'printing now…' graphic and hide it when the print is done. Like what the Game Boy Camera does when you print a picture.
My workaround at the moment, is to play around with timers, which is not ideal.

Advanced Dialogue displays over sprites

Hello Pautomas, I saw in Discord that plugin issues should be discussed here.
As you can see in the image (hope it uploads correctly), dialogues on top get overlayed on top of sprites.
I'm using GB Studio ver 3.2.1 and I've made sure I ejected the engine (and it happened since ver 3.2).

This also happens with text at the bottom of the screen.

Is this an easy fix or is it something hard and time consumable?

Thanks for reading my inquiry.