ProjectSetup.md

Project Setup

BlingoEngine runs on multiple frameworks by delegating platform specific work to an IBlingoFrameworkFactory. The factory provides rendering, input, sound and other services for the engine. Use RegisterBlingoEngine to configure the engine and select the factory for your target framework.

Basic registration

using BlingoEngine.SDL2; // or BlingoEngine.LGodot
using BlingoEngine.Setup;
using Microsoft.Extensions.DependencyInjection;

var services = new ServiceCollection();
services.RegisterBlingoEngine(cfg => cfg
    // Choose one of the available framework factories
    .WithBlingoSdlEngine("MyGame", 1280, 960)       // SDL2 Director window
    // .WithBlingoGodotEngine(this)                // Godot scene
    .SetProjectFactory<MyGameProjectFactory>()     // loads casts and movies
    .BuildAndRunProject());

var provider = services.BuildServiceProvider();
// For SDL2, start the loop:
provider.GetRequiredService<SdlRootContext>().Run();

WithBlingoSdlEngine(title, width, height) defines the Director window size; ensure these values exceed the stage dimensions.

SetProjectFactory<T>() registers your IBlingoProjectFactory implementation which loads cast libraries and the startup movie. BuildAndRunProject() wires everything together and prepares the engine to run.

Sample IBlingoProjectFactory

This factory wires fonts, a 640×480 stage, movie scripts, and custom services before the engine starts.

using BlingoEngine.Projects;
using BlingoEngine.Setup;
using Microsoft.Extensions.DependencyInjection;

public class MyGameProjectFactory : IBlingoProjectFactory
{
    public void Setup(IBlingoEngineRegistration config)
    {
        config
            .AddFont("Arcade", Path.Combine("Media", "Fonts", "arcade.ttf"))
            .AddFont("Tahoma", Path.Combine("Media", "Fonts", "Tahoma.ttf"))
            .WithProjectSettings(s =>
            {
                s.ProjectFolder = "TetriGrounds";
                s.ProjectName = "TetriGrounds";
                s.MaxSpriteChannelCount = 300;
                s.StageWidth = 640;
                s.StageHeight = 480;
            })
            .ForMovie("Intro", s => s
                .AddScriptsFromAssembly()

                // As an example, you can add them manually too:

                // .AddMovieScript<StartMoviesScript>()    // Movie script
                // .AddBehavior<MouseDownNavigateBehavior>() // Behavior
                // .AddParentScript<BlockParent>()     // Parent script
            )
            .ServicesBlingo(s => s
                .AddSingleton<ITetriGroundsCore, TetriGroundsCore>()
                .AddSingleton<GlobalVars>()
            );
    }

    public async Task LoadCastLibsAsync(IBlingoCastLibsContainer castlibs, BlingoPlayer player)
        => await player.LoadCastLibFromCsvAsync("Data", Path.Combine("Media", "Data", "Members.csv"));

    public Task<IBlingoMovie?> LoadStartupMovieAsync(IBlingoServiceProvider services, BlingoPlayer player)
        => Task.FromResult<IBlingoMovie?>(player.NewMovie("Intro"));

    public void Run(IBlingoMovie movie, bool autoPlayMovie)
    {
        if (autoPlayMovie) movie.Play();
    }
}

This implementation defines four required methods:

• Setup(IBlingoEngineRegistration config) registers fonts, project settings (including the 640×480 stage), movies, and services.
• LoadCastLibsAsync(IBlingoCastLibsContainer castlibs, BlingoPlayer player) loads external cast libraries using the provided player.
• LoadStartupMovieAsync(IBlingoServiceProvider services, BlingoPlayer player) chooses the movie that starts first.
• Run(IBlingoMovie movie, bool autoPlayMovie) finalizes startup and optionally plays the movie automatically.

Set properties of members

InitMembers receives the running BlingoPlayer so you can fetch cast libraries and adjust members.

public void InitMembers(BlingoPlayer player)
{
    var textColor = BlingoColor.FromHex("#999966");
    var text = player.CastLib(2).GetMember<BlingoMemberText>("T_data");
    text!.TextColor = textColor;
}

Add labels

SetScoreLabel(frame, label) tags a frame number with a label string for navigation.

public void AddLabels()
{
    _movie.SetScoreLabel(2, "Intro");
    _movie.SetScoreLabel(60, "Game");
    _movie.SetScoreLabel(75, "FilmLoop Test");
}

Adding sprites

AddSprite(channel, beginFrame, endFrame, x, y, configure) creates a sprite on a channel for the frame range and positions it at (x, y). The optional configure action lets you tweak the sprite immediately after creation.

_movie.AddSprite(9, 60, 64, 519, 343, sprite =>
{
    sprite.SetMember("B_Play")
          .AddBehavior<ButtonStartGameBehavior>();
});

Add a frame script

AddFrameBehavior<T>(frame) attaches behavior T to the specified frame number.

_movie.AddFrameBehavior<GameStopBehavior>(60);

Director

To enable the optional Director interface, use the dedicated registration method (currently Godot only):

services.RegisterBlingoEngine(cfg => cfg
    .WithDirectorGodotEngine(rootNode)
    .SetProjectFactory<MyGameProjectFactory>()
    .BuildAndRunProject());

The stage width and height configured in Setup define the playable stage area. The Director window should be larger and is configured via the runtime (for SDL2 through WithBlingoSdlEngine and for Godot via project settings). All examples here use a 640×480 stage.

Each framework exposes its own factory type (SdlFactory, GodotFactory, …). You can pass a callback to the WithBlingo*Engine method to tweak the factory before the engine starts.

Conditional Director usage

You can enable the Director interface only in debug builds by defining a compile‑time constant in your project file:

<PropertyGroup Condition="'$(Configuration)' == 'Debug'">
  <DefineConstants>$(DefineConstants);WITH_DIRECTOR</DefineConstants>
</PropertyGroup>

Then switch registration based on that constant:

#if WITH_DIRECTOR
services.RegisterBlingoEngine(cfg => cfg
    .WithDirectorGodotEngine(rootNode)
    .SetProjectFactory<MyGameProjectFactory>()
    .BuildAndRunProject());
#else
services.RegisterBlingoEngine(cfg => cfg
    .WithBlingoGodotEngine(rootNode)
    .SetProjectFactory<MyGameProjectFactory>()
    .BuildAndRunProject());
#endif

See SDLSetup and GodotSetup for framework specific notes.