Aller au contenu principal

Api References

Intro​

attention

The current API is still in Alpha and could change during development!

The API is managed by the SDK.

The SDK is the main entry point for module developers and is used to create modules, but also by the engine itself. It's made in a way that it's dependency is as low as possible to not force module developers to multiply the size of their module.

For the engine, we use a service locator pattern to access different parts of the engine. Each parts of the engine will define their service inside the SDK, and module developers can access these services to interact with the engine.

We have four main service categories:

  • EngineServices: Those are the main services of the engine, they are defined by the RPGCreator.Core project, and are used to access cores features, like (but not limited to) AssetsManager, SerializerService, UndoRedoService,...
  • RuntimeServices: Those are the services related to the runtime (When the game is running), they are defined by two different projects in code, RPGCreator.Player and RPGCreator.RTP, and are used to access features related to the runtime, like (but not limited to) MapService, LayerService, RenderService, ...
  • EditorUIServices: Those are the services related to the editor UI, they are defined by the RPGCreator.UI project, and are used to edit, or interact with the editor UI, like (but not limited to) DialogService, MenuService, ExtensionManager, ...
  • RegistryServices: Those are the services related to the registry, they are defined by different projects, but mostly by the RPGCreator.Core and RPGCreator.UI projects, and are used to register different things, like (but not limited to): AssetType, Action, Tool, ...

And with that, we also have the 'state' of the engine, which are accessed by:

  • GlobalStates: This is where the engine store all the global states of the engine, like EngineMode, EditorState, ProjectState, MapState,...
Philosophy

By fragmenting the API this way, we ensure that modules have the same power as the engine's internal components. If the engine can do it, your module can too.

Global methods​

Those are methods that can be found in all four services (Engine, Runtime, EditorUi, Registry).

IsServiceReady<T>​

Allow checking if a service is ready (registered) in the service provider.

Flags​

public static

Parameters​

  • [Optional] string groupName = "default"
    The groupName of the service you want to check. GroupName are a way to have multiple same services loaded if needed.

TypeParam​

  • Type <T>
    <T> need to be a class, heriting IService.

Return​

  • bool
    True if the service is registered and ready, False otherwise.

Example​

Let's imagine we have a service class declared like this:

public class MyServiceDummy : IService
{}

We can do this to check if this class has been registered inside the EngineServices:

if(EngineServices.IsServiceReady<MyServiceDummy>())
{
}

/// If we wanted to check if it was inside another groupe than 'default' we can:
if(EngineServices.IsServiceReady<MyServiceDummy>("MyCustomGroup"))
{
}

OnceServiceReady<T>​

Allow providing an action that will be executed once the specified service is registered.
If the service is already registered, then the provided action will be executed immediately.

Flags​

public static

Parameters​

  • Action<T> actionToExecute
    The action that will be executed once the specified service has been registered. It will be provided the service registered.
  • [Optional] string groupName = "default"
    The groupName of the service you want to check.

TypeParam​

  • Type <T>
    <T> need to be a class, heriting IService.
    It will define what the actionToExecute will wait before being executed. It will also be provided as an argument to actionToExecute.

Return: Void​

Example​

Let's imagine we have a service class declared like this:

public class MyServiceDummy : IService
{
    public void MyMethod()
    {
        Logger.Debug("Hello World!");
    }
}

If we can't say WHEN this service will be ready, we can do this to only use it once it's ready:

{

EngineServices.OnceServiceReady((MyServiceDummy dummy) => {

    // Write 'Hello World!' inside the console only
    // When the service has been registered.
    dummy.MyMethod();

});

/// If we wanted to wait for the same service, but in a different group, we can do this
EngineServices.OnceServiceReady((MyServiceDummy dummy) => {

    // Write 'Hello World!' inside the console only
    // When the service has been registered INSIDE the 'MyCustomGroup' group.
    dummy.MyMethod();

}, "MyCustomGroup");

}

GetService<T>​

Get the service (<T>) currently registered.

attention

This method can throw EngineCriticalException if you try to get a service that isn't currently registered.
We advise you to use OnceServiceReady method if you don't exactly know what you're doing!.

Flags​

public static

Parameters​

  • [Optional] string groupName = "default"
    The groupName of the service you want to check. GroupName are a way to have multiple same services loaded if needed.

TypeParam​

  • Type <T>
    <T> need to be a class, heriting IService.
    This is the service that you want to get.

Return​

  • T
    The service found inside the service provider, or an EngineCriticalException if the service couldn't be found!

Example​

Let's imagine we have a service class declared like this:

public class MyServiceDummy : IService
{
    public void MyMethod()
    {
        Logger.Debug("Hello World!");
    }
}

And that this service HAS BEEN registered, we can then do that to get it:

{

var myService = EngineServices.GetService<MyServiceDummy>();
myService.MyMethod();

/// If we want to get the service from another group, we can do this
var myServiceFromAnotherGroup = EngineServices.GetService<MyServiceDummy>("MyCustomGroup");
myServiceFromAnotherGroup.MyMethod();

/// But be aware that if the service has been declared inside the "default" group,
/// you WILL NOT be able to get it from "MyCustomGroup" and vice-versa.

}

RegisterService<T>​

This method allows you to register a custom service inside the service provider.

attention

YOU CAN'T register a custom service inside the 'default' group!

Flags​

public static

Parameters​

  • T service
    The service instance you want to register.
  • string groupName
    The group where this instance will be registered. It CAN'T be 'default' as this is reserved by the engine core!

TypeParam​

  • Type <T>
    <T> need to be a class, heriting IService.
    This is the service type that you want to register.

Return: Void​

Example​

Let's imagine we have a service class declared like this:

public class MyServiceDummy : IService
{
    public void MyMethod()
    {
        Logger.Debug("Hello World!");
    }
}

We can then register it inside the service provider like this:

{

var myService = new MyServiceDummy();
EngineServices.RegisterService(myService, "MyCustomGroup");

// And get it like that
EngineServices.GetService<MyServiceDummy>("MyCustomGroup").MyMethod();

// or like this
EngineServices.OnceServiceReady((MyServiceDummy dummy) => {

    dummy.MyMethod();

}, "MyCustomGroup");

/// IF we try to do this:
EngineService.RegisterService(myService, "default");
/// The engine will stop, and throw an 'EngineCriticalException'.

}