BenMakesGames.PlayPlayMini.UI
4.4.0
Prefix Reserved
See the version list below for details.
dotnet add package BenMakesGames.PlayPlayMini.UI --version 4.4.0
NuGet\Install-Package BenMakesGames.PlayPlayMini.UI -Version 4.4.0
<PackageReference Include="BenMakesGames.PlayPlayMini.UI" Version="4.4.0" />
paket add BenMakesGames.PlayPlayMini.UI --version 4.4.0
#r "nuget: BenMakesGames.PlayPlayMini.UI, 4.4.0"
// Install BenMakesGames.PlayPlayMini.UI as a Cake Addin #addin nuget:?package=BenMakesGames.PlayPlayMini.UI&version=4.4.0 // Install BenMakesGames.PlayPlayMini.UI as a Cake Tool #tool nuget:?package=BenMakesGames.PlayPlayMini.UI&version=4.4.0
What Is It?
PlayPlayMini.UI
is an extension for PlayPlayMini
, adding a skinnable, object-oriented UI framework.
How to Use
This documentation assumes you already have a project that uses the PlayPlayMini
framework. If not, check out the PlayPlayMini
framework documentation to get started with it!
Load Required Resources
PlayPlayMini.UI
requires a couple spritesheets, an image, and a font to be loaded. These are used for rendering buttons, checkbox, and the mouse cursor.
var gsmBuilder = new GameStateManagerBuilder()
.AddAssets(new IAsset[] {
...
new PictureMeta("Cursor", "Graphics/Cursor", true), // preload, so we can display on loading screen
new SpriteSheetMeta("Button", "Graphics/Button", 4, 16),
new SpriteSheetMeta("Checkbox", "Graphics/Checkbox", 10, 8),
new FontMeta("Font", "Graphics/Font", 6, 8),
})
...
;
At the time of this writing, PlayPlayMini.UI
is not as flexible as it could be with the size of the UI elements it renders. For the best effect, use a font close to 8 pixels in height.
Configure UI Framework
Setup Custom Mouse
In the PlayPlayMini
, it is best-practice to have a Startup GameState which displays a loading message to the player while your deferred resources load.
One of the primary reasons for using PlayPlayMini.UI
is for a mouse-driven UI. If you're not already doing so, you should configure the MouseManager
in your Startup GameState
. For example:
public class sealed Startup : GameState
{
private MouseManager Mouse { get; }
public Startup(MouseManager mouse, ...)
{
Mouse = mouse;
...
Mouse.UseCustomCursor("Cursor", (3, 1)); // the Picture named "Cursor", loaded in previous code sample
}
}
Create Theme Provider
PlayPlayMini.UI
has a theming system that allows you to control the appearance of buttons, checkboxes, etc, and even change them at run-time. To facilitate this, you need to create a theme provider that tells PlayPlayMini.UI
which theme to use.
The theme provider must extend UIThemeProvider
, and be registered as a service. Here's an example implementation:
[AutoRegister(InstanceOf = typeof(UIThemeProvider))]
public sealed class ThemeProvider: UIThemeProvider
{
protected override Theme CurrentTheme { get; set; } = new(
WindowColor: Color.Orange,
FontName: "Font",
ButtonSpriteSheetName: "Button",
ButtonLabelColor: Color.White,
ButtonLabelDisabledColor: Color.Gray,
CheckboxSpriteSheetName: "Checkbox"
);
}
To change the theme, call SetTheme
. The following example assumes you have a pre-defined list of themes you want to let the players from, but you're free to make more-complex UIs, of course:
public sealed class SettingsMenu: GameState
{
private static readonly List<Theme> AvailableThemes = { ... };
private ThemeProvider ThemeProvider { get; }
...
public SettingsMenu(ThemeProvider themeProvider, ...)
{
ThemeProvider = themeProvider;
...
}
private void SelectTheme(int themeIndex)
{
ThemeProvider.SetTheme(AvailableThemes[themeIndex]); // set the theme!
}
...
}
In a GameState
, Request an Instance of UIService
, and Configure It
Each instance of UIService
that's requested is a new instance. A UIService
instance contains UI components, such as buttons, and is responsible for handling mouse events that take place within it, including hovers & clicks, and notifying the appropriate component(s) of these events.
Example:
public class sealed PauseMenu: GameState
{
private UIService UI { get; }
...
public PauseMenu(UIService ui, ...)
{
UI = ui;
...
InitUI();
}
// it's not required to create a dedicated method for building the UI
// (you'll only ever call it once), but it helps keep the constructor tidy.
private void InitUI()
{
// Window is a UI component provided by PlayPlayMini.UI
var window = new Window(
UI, // instance of the UIService
20, 20, // x, y coordinate to position the window
150, 100, // width, height of the window
"Paused" // title
);
var resume = new Button(UI, 4, 16, "Resume", ResumeGameHandler);
var settings = new Button(UI, 4, 33, "Settings", SettingsHandler);
var saveAndQuit = new Button(UI, 4, 50, "Save & Quit", SaveAndQuitHandler);
// add the buttons to the window:
window.AddUIElements(resume, settings, saveAndQuit);
// and the window to the UI canvas:
UI.Canvas.AddUIElements(window);
}
private void ResumeGameHandler(ClickEvent click)
{
// x, y coordinates that click took place, relative to the button's position
// do something
}
private void SettingsHandler(ClickEvent click)
{
// do something
}
private void SaveAndQuitHandler(ClickEvent click)
{
// do something
}
public override void ActiveUpdate(GameTime gameTime)
{
UI.ActiveUpdate(gameTime);
}
public override void AlwaysDraw(GameTime gameTime)
{
UI.AlwaysDraw(gameTime);
}
public override void ActiveDraw(GameTime gameTime)
{
UI.ActiveDraw(gameTime);
// note: there is no need to manually update or draw the mouse cursor;
// if you're using a UIService, it will handle the mouse for you.
}
}
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
-
net8.0
- BenMakesGames.PlayPlayMini (>= 4.4.0)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
Version | Downloads | Last updated |
---|---|---|
5.0.0 | 141 | 8/17/2024 |
4.7.1 | 102 | 5/28/2024 |
4.7.0 | 107 | 5/24/2024 |
4.5.0 | 129 | 3/23/2024 |
4.4.0 | 120 | 3/2/2024 |
4.3.0 | 118 | 2/25/2024 |
4.2.0 | 117 | 2/22/2024 |
4.1.0 | 127 | 2/12/2024 |
4.0.1 | 238 | 11/25/2023 |
4.0.0 | 110 | 11/25/2023 |
3.4.0 | 133 | 9/18/2023 |
3.3.0 | 139 | 9/17/2023 |
3.2.1 | 171 | 6/30/2023 |
3.2.0 | 201 | 4/16/2023 |
3.1.0 | 247 | 3/12/2023 |
3.0.3 | 231 | 3/11/2023 |
3.0.2 | 321 | 1/8/2023 |
3.0.1 | 286 | 1/7/2023 |
3.0.0 | 344 | 11/16/2022 |
2.0.1 | 397 | 10/9/2022 |
2.0.0 | 448 | 9/24/2022 |
1.0.0 | 489 | 9/18/2022 |
0.10.0 | 431 | 5/12/2022 |
0.9.0 | 448 | 1/15/2022 |