BLine Web 2027 Beta 2¶

Early beta

This guide covers v1.0.0-beta.2, titled BLine Web 2027 Beta 2, verified against source revision b12be8e4035555abfa0b140f1240d626b0202a82. Test existing projects on copies. The current website and ordinary editor tutorials remain on v0.1.0-alpha.12.

Beta 2 adds reusable project event keys, interactive Settings lessons, clearer canvas editing, and save recovery. This guide covers the changes since Beta 1. The ordinary tutorials and editor screenshots elsewhere on this site still describe v0.1.0-alpha.12; the documented BLine-Lib version remains unchanged.

Choose the editor and keep a backup¶

The current alpha.12 editor and its pinned desktop downloads remain separate from the preview.
The beta website is a moving preview address, not a version-pinned copy. Keep using that address and the same browser profile to retain its browser projects and offline copy.
For desktop, use the BLine Web 2027 Beta 2 release, tag v1.0.0-beta.2. The app installs as BLine Web Beta, separate from the current alpha app. Beta updates share the beta app's settings and storage.

Before opening an existing project, export a project archive or copy the complete desktop project folder, including hidden files. Separate apps can still write to the same physical folder. Keep the original if you need to return to Beta 1 or alpha.12: older editors may not understand the new project metadata.

Coming from alpha.12, follow Bring an existing project into beta for the import choices and config.json / project.json / paths/ layout. Beta 2 keeps that layout. Its editor settings are stored as follows:

Setting	Saved with the project and project archive?
Registered event Lib Keys, including unused keys	Yes
Legacy appearance	Yes
Blank Meter Grid length and width	Yes
Protrusion configuration and show/hide event-key lists	Yes
Selected field background and custom field images	No; these remain local to the app/browser

These editor settings do not add robot actions. Individual path files still carry their event elements and lib_key values; robot code supplies the matching behavior.

Move existing elements while drawing¶

Drag the center of an existing waypoint or translation target with any canvas tool selected, including a placement tool or the curve tool. You can adjust that position and continue using the same tool. A locked linked position remains locked. The pointer changes to a grab cursor over a movable center and a rotation cursor over an available heading handle.

The simulated path and robot preview update during a drag, with smooth transitions between completed simulation results. Release the drag to inspect the committed result, or press Esc to cancel it. This display smoothing does not turn the authored polyline into a spline or establish that the robot can follow it physically.

Rotation (deg) is the property's UI label. Rotation is also called heading: the direction the robot faces, which can differ from its direction of travel.

Read the footprint and choose its appearance¶

Set File → Settings → Robot → Size to your robot's outside bumper length and width in meters. The footprint represents those outer dimensions. A protrusion's distance is the additional reach beyond the chosen bumper edge. Rounded protrusion outlines join the footprint, helping you judge the full occupied area.

Translation and event markers scale with the field view. The updated element symbols also appear in the tool rail and inspector. To use the triangular heading marker, enable File → Settings → Robot → Appearance → Legacy appearance, then Save. This affects the canvas robots, including the simulation preview, and the matching waypoint icons in the tool rail and inspector. Hovering the front edge still exposes the rotation handle.

The footprint is a clearance aid. It does not detect collisions or change the robot's hardware configuration.

Reuse and manage event Lib Keys¶

A Lib Key names an action, such as startIntake. Beta 2 keeps a project-wide list so you can use the same spelling on several paths. The list includes explicitly registered keys and keys already used by path events or the protrusion show/hide settings. Keys retain their capitalization; use the exact spelling registered in robot code.

Assign a key to an event¶

Select an event and find Lib Key in its properties.
Type a key's prefix. Press Tab to complete a suggestion, use Up/Down and Enter, or click a suggestion. Scroll the suggestion list if more keys are available.
To introduce a new key, type it in full and commit it with Enter or by leaving the field. It becomes available elsewhere in the project. Clearing this one event's field does not remove the saved registration.

The Manage event triggers button beside Lib Key opens the project manager directly. You can also open File → Settings → Event Triggers.

Manage keys across the project¶

Use the search field to filter the list. Click +, enter a new key, and confirm with the checkmark to register it without placing an event. An already registered name cannot be added again. Each row's ⋯ menu offers:

Action	Effect when you save Settings
Rename All	Replaces the exact key in every path event, its registration, and both protrusion key lists in this project.
Rename to an existing key	Combines those uses under the destination key. It does not combine or remove event elements.
Duplicate	Proposes a new key such as `startIntake_copy`; confirm its name to register it. It does not copy event elements or their positions.
Delete → Clear key	Removes the registration, clears matching path-event Lib Keys, and removes the key from protrusion lists. The event elements stay in place.

Click Save at the bottom of Settings to apply the changes, or Cancel to abandon the settings draft. Applied project edits support Undo and Redo. Automatic constraint regeneration preserves the Redo history after an undo. After clearing a key, assign new keys to the remaining events or remove unwanted event elements; review Path health for blank keys.

The use/uses count is the number of event trigger elements using that key across the project's paths. It excludes protrusion settings. A key showing 0 uses may still be assigned to a protrusion list or registered for future use.

Registering or renaming a key here does not edit Java code or register a WPILib action. Update the matching robot registrations yourself; see Events & Command Groups. Simulation shows event timing and protrusion visibility, not execution of your mechanism commands.

Assign protrusion show and hide keys¶

In File → Settings → Robot, turn on Enable Protrusions and set the distance, side, and default state. Use + beside Show On Event Keys or Hide On Event Keys to add one key per row. Each input offers the same project-key suggestions.

For example, add startIntake under Show On Event Keys and stopIntake under Hide On Event Keys, then place those events on the path. Save Settings and play the path to see the extension change state.

Each row's ⋯ menu can Rename, Duplicate, or Remove that assignment. These local list edits do not rename the key across paths. Use Event Triggers → Rename All for a project-wide change. Removing an assignment leaves its registered key available for reuse.

Resize a blank practice field¶

Open File → Settings → Field.
Choose Blank Meter Grid in Field Image.
Set Field Length (m) for the horizontal span and Field Width (m) for the vertical span, then Save. Each accepts 0.5–30 m; the default grid is 18 × 9 m.

The grid lines remain one meter apart. For example, a 12 × 6 m grid changes the planning area without scaling the robot or moving path coordinates. The dimensions belong to this project and survive folder saves and project-archive export/import. On another device, select Blank Meter Grid again because the selected background itself is a local preference.

Keep path filenames recognizable¶

Creating, renaming, or duplicating a path preserves safe capitalization, internal spaces, underscores, Unicode, and punctuation. For example, TEST_AUTO (2)! produces TEST_AUTO (2)!.json. Leading and trailing whitespace is trimmed, and the editor handles the .json suffix. Safe imported filenames retain their spelling.

The Navigator shows the actual filename beneath the path name. Check it after renaming or importing, especially when a robot routine loads that file. A collision, including one differing only in letter case, receives a suffix such as -2.

Names must not contain <, >, :, ", /, \, |, ?, *, or control characters. A filename stem cannot end in a dot or space, or use a reserved device name such as CON, PRN, AUX, NUL, COM1–COM9, or LPT1–LPT9 (including those followed by an extension).

After a rename, update robot code that loads the old filename. For TEST_AUTO (2)!.json, use the exact stem, including case and spaces:

new Path("TEST_AUTO (2)!")

Recover when saving fails¶

If a save fails, a compact recovery dialog appears while your edits remain open. For a missing desktop folder, it says Project folder is missing and shows the folder path.

Choice	When to use it
Retry save	Restore the folder or resolve the storage problem, then try saving again. A restored but changed folder can lead to the existing conflict or metadata-recovery flow.
Recreate folder	For a missing desktop project folder, explicitly create that folder at its original location using the open BLine project. Its parent directory must still exist. This does not restore unrelated files that were in the deleted folder.
Export copy	Save a project archive containing the open edits. Exporting does not repair the original save destination.
Keep editing, the close button, or `Esc`	Dismiss recovery and keep the project open. These choices do not save the pending edits.
Leave without saving	Offered when a project change or desktop close is waiting for a save. It discards changes since the last successful save so that action can proceed.

Normal save does not silently recreate a deleted folder. Recreate folder refuses to replace an existing folder, file, or symlink; if the folder has reappeared, use Retry save to check it. Export a copy if you need to preserve your current work before leaving.

After successful retry or recreation, recovery closes and the status returns to Saved. The old save failure no longer holds up a ready browser update; the update still waits for the normal safe reload conditions. If you dismiss recovery while the problem persists, click Save failed to reopen it.

Browser Save still writes browser storage, and desktop Save/autosave still writes the selected project folder. See Save versus export for robot-ready exports and project archives.

Learn Settings by changing a practice project¶

Open Learn → Lessons from Home or Help and tutorials → Lessons in the editor. Expand Settings, after the Event triggers lesson, to choose:

Sublesson	Practice
Robot	Resize the bumper footprint, configure a protrusion, place show/hide events, and play the result.
Path Defaults	Set translation limits and explore rotation limits and end tolerances.
Field	Choose a field image, resize a blank grid, and inspect the unchanged path coordinates.
Generator	Adjust a safety factor and turn automatic generation off and back on.
Event Triggers	Register and search reusable keys, then explore the project-wide actions.

Lessons use isolated practice projects and restore your project when you leave. Settings walkthroughs show changes as you make them; in your own project, finish Settings with Save. The suggested lesson numbers are practice values, not measured limits for your robot.

Lessons remain available in narrow windows. The lesson card moves below the editor, and each new step starts at its instructions. Scroll the card or Settings panel to reach the remaining controls.

Review generated output and report problems¶

Beta 2 retains the Beta 1 generator workflow. This update does not resolve every generator problem:

A reported slow path still reproduces a 0.05 m/s generated cap with a best-effort result. Treat that output as needing review.
A reported 8.661 m generated handoff radius remains under investigation. Its presence in a saved project is not evidence that it is the appropriate radius.

Inspect automatic radii, maximum-velocity ranged constraints, and Path health, then test incrementally on the robot. Do not treat a completed simulation or a clear health report as physical validation.

Use the bug icon immediately to the right of the path selector to open a report draft. Include the editor version, reproduction steps, and a sample project when useful. See Report a beta issue for what the draft includes and how to submit it.