README.md

ZIRCON

A clean, sleek, runtime debugging console for Roblox

Setup

To begin, it is recommended to do

npm i @rbxts/zircon @rbxts/log

This will install both Zircon, as well as the logging support. It is recommended to use the logging as it can be filtered easily through the Zircon console.

Features

• Zirconium Language Scripting

  Zircon comes inbuilt with a runtime scripting language called Zirconium. This allows you to run scripts against your game during runtime.

  More information on how to set this up, will come when Zircon is closer to being production-ready.

  Supports:

  • Functions

    Using ZirconServer.Registry.RegisterFunction + ZirconFunctionBuilder

  • Namespaces

    Using ZirconServer.Registry.RegisterNamespace + ZirconNamespaceBuilder

  • Enums

    Using ZirconServer.Registry.RegisterEnum + ZirconEnumBuilder

• Structured Logging

  If you want logging for Zircon, you will need to install @rbxts/log.

  Then to use Zircon with Log, you simply do

  import Log from "@rbxts/log";
  import Log, { Logger } from "@rbxts/log";
  import Zircon from "@rbxts/zircon";
  
  Log.SetLogger(
      Logger.configure()
          // ... Any other configurations/enrichers go here.
          .WriteTo(Zircon.Log.Console()) // This will emit any `Log` messages to the Zircon console
          .Create() // Creates the logger from the configuration
  );

  This will need to be done on both the client and server to achieve full logging.

  All logging done through this can be filtered through the console itself. That's the power of structured logging! ;-)

Registering and using Zircon Commands

Below is an example of how to register a command in Zircon:

import { 
    ZirconServer,
    ZirconFunctionBuilder,
    ZirconDefaultGroup,
    ZirconConfigurationBuilder
} from "@rbxts/zircon";
import Log from "@rbxts/log";

const PrintMessage = new ZirconFunctionBuilder("print_message")
    .AddArguments("string")
    .Bind((context, message) => Log.Info(
            "Zircon says {Message} from {Player}", 
            message,
            context.GetExecutor()
    ));

const CreatorCommand = new ZirconFunctionBuilder("kill")
    .AddArguments("player")
    .Bind((context, player) => {
        const character = player.Character;
        if (character) {
            character.BreakJoints()
        }
    });

ZirconServer.Registry.Init(
    new ZirconConfigurationBuilder()
        // Creates a 'creator' group
        .CreateDefaultCreatorGroup()
        // Creates a 'user' group
        .CreateDefaultUserGroup()
        // Adds an executable function called 'print_message', allowed to be executed by `User` (everyone)
        .AddFunction(PrintMessage, [ZirconDefaultGroup.User])
        // Adds an executable function called 'kill' that can only be executed by a creator of the place.
        .AddFunction(CreatorCommand, [ZirconDefaultGroup.Creator])
        // Builds the configuration for Zircon
        .Build()
);

This will create a global print_message that all players can run.

Then if run in Zircon:

The first argument of RegisterFunction takes a ZirconFunctionBuilder - which is the easiest way to build a function. AddArguments takes any number of arguments for types you want, in built types in Zircon you can use a string for. Otherwise you supply the type validator object.

Troubleshooting

Attempted to call AsyncFunction 'ZrSOi4/GetZirconInit' - which has no user defined callback

• You need to call ZirconServer.Registry.Init - an example of that can be found here

Unhandled promise rejection: ... Component returned invalid children ...

• You need to update your version of roact to the latest. That can be done via npm i @rbxts/roact@latest.

More Help & Links

Australis OSS Community