Studio plugin

The Studio plugin, BlinkBlox Editor, keeps your schemas inside the place, edits them with highlighting, autocomplete and live diagnostics, and generates the modules straight into the Explorer. It runs the same parser and generator as the command line, from the same release, so a schema produces the same modules either way. Installation covers getting it.

The pictures on this page are drawn from the plugin’s own interface files – the layout, colours and text are the plugin’s, and the code in them is coloured by the plugin’s own highlighter.

Opening the plugin

The plugin adds a toolbar named BlinkBlox Suite to the Plugins tab, with one button, Editor. Clicking it opens the editor window, docked on the left and titled Configuration Editor; clicking it again closes the window. The button stays highlighted while the window is open.

HomeModelTestViewPlugins

Editor

BlinkBlox Suite

The template

The first time you open the editor in a place, the plugin creates the folder it keeps schemas in and saves a file named Template into it, then opens that file:

Configuration Editor

1

2

3

4

5

6

7

type Example = u8

event MyEvent {

From: Server,

Type: Reliable,

Call: SingleSync,

Data: Example

}

This happens only in a place that has never had the folder. Delete every file and the folder stays, empty: the plugin takes that as your choice and does not bring the template back.

Where schemas are stored

Each schema is a StringValue in ServerStorage.BLINK_CONFIGURATION_FILES: its Name is the file name and its Value is the source. The files are saved with the place, travel with it through Team Create and version history, and never reach a client, because nothing in ServerStorage replicates.

You can manage them in the Explorer like any other instance – rename one, duplicate it, copy it into another place. The side menu reads the folder when it first opens and again after each save or delete, so a file changed in the Explorer shows up there after the next one. The folder keeps the name it had before the plugin was renamed to BlinkBlox, so places set up by older versions keep working.

The side menu

The button at the top of the strip on the left opens the side menu over the editor. It holds every saved file, in name order, each with three buttons: Delete, Edit and Generate. Clicking the menu button again closes it.

Files

Configuration Editor

1

2

3

4

5

6

7

type Example = u8

event MyEvent {

From: Server,

Type: Reliable,

Call: SingleSync,

Data: Example

}

Search

Combat

Inventory

Template

Save

Saving

Configuration Editor

1

2

3

4

5

6

7

type Example = u8

event MyEvent {

From: Server,

Type: Reliable,

Call: SingleSync,

Data: Example

}

Search

Combat

Inventory

Template

Combat

CancelSave

Generating

Configuration Editor

1

2

3

4

5

6

7

type Example = u8

event MyEvent {

From: Server,

Type: Reliable,

Call: SingleSync,

Data: Example

}

Search

Combat

Inventory

Template

Selected
ReplicatedStorage

CancelGenerate

Save

• Edit opens the file in the editor and closes the menu.
• Delete removes the file at once. There is no confirmation.
• Generate opens the generate prompt – see Generating.

Searching

Type into the search box and press Enter to show only the files whose names contain what you typed. The match is plain, case-sensitive text: since 0.28.0, (, [, %, . and - mean themselves rather than being read as a Lua pattern. Clicking the box clears it; press Enter on an empty box to show every file again. Leaving the box without pressing Enter changes nothing.

Saving

Save at the bottom of the menu saves what is in the editor. The first click opens a Name box, filled in with the name of the file you are editing, and turns Save green; the second click saves under that name. A name that is already taken replaces that file’s contents, which is how you save changes to an existing file. Cancel closes the prompt without saving.

Caution

Clicking into the Name box clears it. To save under the name already filled in, press Save again without clicking the box.

Saving under a new name does not switch the editor to the new file: the editor still counts as editing the file you opened, and quick save keeps writing to that one. Open the new file with Edit to carry on in it.

Quick save and clear

The two buttons in the editor’s bottom-right corner work without opening the menu.

• Save (the lower one) saves the editor’s contents over the file you are editing, without asking. If you are not editing a saved file – the text was imported, say – it opens the menu with the save prompt instead.
• Clear (the upper one) empties the editor. It does not touch the saved file.

Both do nothing while the side menu is open.

Caution

After Clear, the editor still counts as editing the same file. Quick-saving then writes the empty text over that file. If you cleared by mistake, reopen the file with Edit instead of saving.

Importing

The button to the left of the search box imports a schema from your computer. Studio opens a file picker for .blink and .txt files, and the one you choose is loaded into the editor. It is not saved and not attached to any file: save it from the menu to keep it in the place.

Generating

Generate on a file opens the generate prompt at the bottom of the menu. Select the destination in the Explorer – the prompt shows its full name under Selected – and press Generate. Until something is selected, the prompt asks you to select a location and Generate is dimmed and does nothing.

Caution

Generate into somewhere both the server and the clients can reach, such as ReplicatedStorage. Generated into ServerStorage or ServerScriptService, the client module cannot be required.

The plugin remembers the last destination between sessions. When the prompt opens with nothing selected, that destination is selected for you; selecting something else in the Explorer overrides it. The destination is remembered by its full name, so after you rename or move it the plugin no longer finds it and you select it again – rather than generating into the old place.

Note

Generating reads the saved file, not the editor. Save first, or you generate the version from before your last edits.

Script injection

Creating scripts is a permission Studio grants plugins separately. The first time you generate, Studio asks whether to allow BlinkBlox Editor to inject scripts; allow it. If it is refused, the plugin opens its error window with File generation failed, plugin doesn’t have script inject permissions. and writes nothing. You can grant it later from Plugins > Manage Plugins.

The output

The plugin writes three ModuleScripts into a folder named Blink under the destination, creating the folder if it is not there:

Explorer

ReplicatedStorage

Blink

Client

Server

Types

Wrapperyours, left alone

ServerStorage

BLINK_CONFIGURATION_FILES

Combat

Inventory

Template

• Server is required from server scripts, Client from LocalScripts: local Net = require(ReplicatedStorage.Blink.Server).
• Types holds the schema’s exported types, for code that wants to name them.

The folder keeps the name Blink from before the rename, so code that requires through it keeps working.

Generating again updates the three modules in place. They stay the same instances, so an open script tab, a breakpoint, or an ObjectValue pointing at one survives regeneration. Nothing else in the folder is touched: a wrapper module or configuration script you keep beside the generated ones stays. Before 0.23.0 the plugin emptied the folder on every generation. The one exception is an instance of another class sitting on one of the three names – a Folder named Server, say – which is replaced, with a warning in the Output window saying so.

The modules are written through ScriptEditorService, so a large schema whose output passes the 200,000 characters a script’s Source property accepts still generates.

Profiles

A schema that uses @profile is generated as release unless told otherwise. To generate another profile, select the file in ServerStorage.BLINK_CONFIGURATION_FILES and add a string attribute named Profile in the Properties window, set to dev, debug, test or release. Any other value, or an attribute of another type, stops generation with an error naming it – Unknown profile “beta” on Combat: expected dev, debug, test or release. The attribute belongs to the file, so each schema keeps its own profile.

Imports

An import in the plugin names another saved file rather than a path on disk: import "Shared" reads the file saved as Shared. See Imports in the Studio plugin.

Errors

If the file does not compile, nothing is written and a floating Error window opens with the compiler’s diagnostic – the same one the command line prints, with a plainer gutter. For the schema in Live diagnostics below, with Hit misspelt as Hitt on line 14:

Error

[E3007] Error: Unknown reference
    ╭-[input.blink:1:15]
    |
014 | 	Data: Hitt
             -----
               |
               ╰-- Unknown reference
    |
----╯

A schema always reports itself as input.blink here, since the plugin compiles text rather than a file on disk. Warnings do not stop generation; they are printed to the Output window. Diagnostics lists every code.

The editor

Highlighting

The editor colours the schema as you type: keywords in blue, primitives in teal, numbers and Instance classes in pale green, names you reference in light blue. A field name is left white, which is how Hit: reads differently from a reference to Hit.

Autocomplete

A popup offers completions as you type:

• At the start of a line, the declaration keywords: set, map, type, enum, struct, event, function, import, scope and export.
• After a field’s : or a declaration’s =, the primitive types and the names your schema declares – as of the last time it parsed without an error.

Tab accepts the highlighted item and Up / Down move through the list. A keyword expands to its skeleton with the cursor where the name goes: struct becomes a struct declaration with empty braces, map a map with an empty []: pair, and so on.

Configuration Editor

1

2

3

4

5

6

type Health = u8(0..100)

struct Hit {

Target: Instance(Player),

Damage: u^u8u16u32unknown

}

Brackets and indentation

Typing (, [, { or < adds its closing bracket when nothing but a closing bracket or the end of the line follows the cursor, and deleting an opening bracket with a closing one right after it deletes both. Pressing Enter after a { indents the new line by one more tab and moves anything after the cursor – the closing brace, usually – to a line of its own. Pressing Enter at the end of an indented line keeps the indentation.

Live diagnostics

The editor parses the schema on every keystroke and marks the first problem it finds with a row of carets under where the problem starts: red for an error, amber for a warning. Hover over the carets to read the diagnostic – its severity, name, message and code, then what each label says with the line it is on. The picture above shows the same thing mid-word: u is not a type yet, so it is marked until you finish typing it.

Error

Configuration Editor

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

option DefaultRate = 30

type Health = u8(0..100)

struct Hit {

Target: Instance(Player),

Damage: u16(0..500)

}

event Damage {

From: Client,

Type: Reliable,

Call: SingleSync,

Data: Hitt^^^^Error AnalyzeUnknownReference: Unknown reference BlinkBlox(3007) Unknown reference [L14]

}

Warning

Configuration Editor

1

2

3

4

5

6

7

8

9

type Health = u8(0..100)

event HealthChanged^^^^^^^^^^^^^Warning AnalyzeMissingRateLimit: Rate limiting a Server event has no effect BlinkBlox(3020) This event is sent BY the server, not to it [L3] {

From: Server,

Type: Unreliable,

Call: SingleSync,

Rate: 10,

Data: Health

}

One diagnostic is shown at a time: the error when the schema does not parse, otherwise its first warning. Only the first line of what it points at is marked. Before 0.28.0 the editor never showed a warning at all – each one was cleared by the parse that raised it and printed to the Output window on every keystroke instead. Warnings now appear here and are not printed.

Large files

The editor does a fixed amount of work per keystroke however long the schema is. It draws the document once per change, and a diagnostic costs the same wherever it is – until 0.23.0, a diagnostic on line 800 rebuilt 800 instances on every keystroke, about 39ms. Line numbers past the first 2,000 are created as they are needed; a longer document used to crash the editor. The mouse wheel scrolls two lines at a time.

Tip

Right-click the menu button twice within a second to toggle a timing overlay that breaks down each keystroke – highlighting, analysis, completion and the rest. It is there for working on the plugin, and useful if a schema ever feels slow.