Build, Test, and Debug

Code Lab is a project compiler, not a one-file runner. Every source below the custom root participates in one HyperionX.Custom.dll, and successful editor compilation is only the first gate.

Paths

The default source root is:

%USERPROFILE%\Documents\HyperionX\Bin\Custom

Code Lab writes:

%USERPROFILE%\Documents\HyperionX\Bin\Custom\bin\Debug\HyperionX.Custom.dll
%USERPROFILE%\Documents\HyperionX\Bin\Custom\bin\Debug\HyperionX.Custom.pdb

The default installed configuration also loads from the Debug folder. A customized project/output setting can change the runtime path; check Options > Project and the HyperionX log before copying artifacts manually.

Two builds are involved

Code Lab and the desktop runtime compile the same source tree for different purposes.

1. Code Lab build

Selecting Build in Code Lab:

1. Saves the active editor buffer into its category folder.
2. Reads every .cs file below the custom root except files under bin and obj.
3. Normalizes the legacy spelling State.Configure to State.Configured.
4. Adds narrow global imports, editor compatibility support, and in-memory indicator helper sources.
5. Emits a Debug HyperionX.Custom.dll and PDB.
6. Shows Roslyn errors and warnings in the Code Lab diagnostics view.

This pass does not by itself replace every object already running in the desktop process.

2. Desktop runtime build and load

At startup, from the chart Compile Project action, or when an indicator/strategy selector detects stale source, HyperionX:

1. Unloads successfully loaded add-ons and clears custom bar registrations.
2. Unloads the previous collectible custom assembly.
3. Reads the entire custom source tree again.
4. Generates indicator convenience helpers in memory.
5. Emits and loads a new HyperionX.Custom.dll.
6. Discovers scripts, research modules, bar builders, and add-ons.
7. Recreates eligible chart objects when reload-on-compile is enabled.

Runtime activation is authoritative. A green Code Lab build followed by a runtime-build error is not a deployable extension.

Write self-contained source

Code Lab currently supplies imports and compatibility members that the runtime pass does not reproduce. Put every required using directive in the source, use State.Configured, and depend only on documented members. Always complete the runtime activation check.

The normal edit loop

1. Start from the closest Code Lab template.
2. Give every public class a unique name and align the file name with it.
3. Save the source in its category folder.
4. Disable running strategies and remove affected instances before the runtime build.
5. Select Build in Code Lab and resolve all errors.
6. Trigger runtime activation by opening the relevant selector or using Compile Project.
7. Create a fresh instance in its actual host.
8. Inspect the HyperionX log and verify a written expected result.
9. Build a second time to test reload and cleanup.

An enabled strategy remains on the old assembly during a runtime recompile and is marked as out of date. Disable it before compiling. If it remained enabled, toggling Enabled off and on later reuses the same object; remove and add the strategy again, or reload its owning host.

Indicators can be recreated automatically when reload-on-compile is enabled, but a fresh instance remains the safest verification target. Bar builders and successfully loaded add-ons are re-registered from the new assembly.

Atomic-build consequences

• One unrelated syntax error can block every custom extension.
• Duplicate class names can break generated helpers or make discovery ambiguous.
• Moving a file to another folder below Custom does not exclude it.
• To quarantine a file, move it completely outside the custom root or change its extension.
• Never edit bin or obj; those are output and intermediate folders.
• A failed runtime compile can leave no current custom assembly loaded. Resolve the error and activate again.

Start with the first diagnostic

One syntax or type error can create many follow-on messages. Fix the earliest source location, rebuild, and reassess.

Assembly and dependency boundary

Code Lab compiles against a fixed set of HyperionX, .NET, WPF, and already loaded process assemblies. It does not restore an independent NuGet graph for each extension.

• Prefer APIs already referenced by the installed Code Lab runtime.
• Do not assume adding PackageReference to an unrelated project changes the Code Lab build.
• Do not distribute copied HyperionX binaries with source extensions.
• Treat manually copied third-party DLLs as unsupported unless a HyperionX release documents that deployment path.
• Use an external process and the local desktop API when an integration needs dependency isolation.

Indicator helper generation

Code Lab and the runtime use the same in-memory indicator helper generator. It supports file-scoped and block-scoped namespaces and does not append generated code to customer source.

For a helper such as MyAverage(14):

• Put the class in HyperionX.Custom.Indicators.
• Derive the class directly from Indicator.
• Mark helper parameters with [HyperionXProperty].
• Keep the class name unique.
• Do not copy another platform's generated cache region.

An indirect subclass can still be discovered by base type, but the current generator only emits helpers for a class whose declared base has the simple name Indicator.

See Parameters and generated helpers for the generated signature and cache behavior.

SDK adapter status

The active release-candidate source also generates native hosts for direct HyperionX.SDK.IndicatorBase and StrategyBase subclasses. That adapter is Preview and unreleased; it is not the release-safe authoring path for an existing 1.1.10 installation. Use HyperionX.Custom for public samples and verify API status before testing SDK-shaped source.

Diagnose compile and activation failures

For each error, check:

1. The file and line belong to the source you intended to compile.
2. The namespace and base type match the extension family.
3. The member exists in the current HyperionX reference.
4. Required using directives are explicit and unambiguous.
5. DateTime[0] means bar time and System.DateTime.Now means machine clock time.
6. No copied generated region declares duplicate support types.
7. The source passes desktop activation, not only the Code Lab pass.

Symptom	Most likely check
Code Lab fails	Fix the first diagnostic anywhere in the custom tree.
Code Lab succeeds; runtime fails	Remove editor-only aliases/import assumptions and read the main HyperionX log.
Type does not appear	Confirm a concrete class, correct base type, successful runtime load, and the intended selector.
Helper method is missing	Use the exact indicator namespace, a direct Indicator base, and [HyperionXProperty] parameters.
Old behavior remains	Stop and recreate the instance; an enabled strategy can keep its old assembly.
Add-on did not start	Complete a desktop runtime load or restart HyperionX; Code Lab emission alone is not activation.

More symptom-specific fixes are in Script Troubleshooting.

Runtime verification by extension type

Type	Minimum verification
Indicator	Add to a chart; change parameters; scroll, zoom, resize, change interval, reload, and inspect outputs/logs.
Strategy	Backtest, then playback or simulation on an explicitly selected LocalPaper account; inspect orders, fills, positions, stops, targets, errors, and stop behavior. Playback does not select LocalPaper; the current release-candidate build rejects external-account mutations while Playback is active.
Bar type	Compare deterministic candles across historical construction, incremental updates, reset, and flush.
Optimizer	Run a tiny known grid and confirm combination count, cancellation, retained results, and ranking.
Fitness	Verify profitable, losing, empty, and non-finite result cases.
Money management	Verify valid, minimum, maximum, zero, and preserve-requested-quantity cases in every intended environment.
Commission	Verify full exits, partial exits, quantity, asset class, and a zero-cost baseline.
Add-on	Test first load, second load, failed load, unload, event cleanup, and UI responsiveness.

Logs and output

Indicators and strategies can use:

Print("calculation checkpoint");
Log("platform log message");
Ctx.Log.Info("structured information");
Ctx.Log.Error("structured error");

Add-ons use their protected Print(...) method. Avoid per-tick logging except during a short diagnostic run; high-frequency output can hide the useful event and reduce responsiveness.

Runtime failure policy

Use early-bar guards, null checks, bounded loops, and explicit no-data handling. The host adds a final isolation layer:

• A live indicator is disabled after ten consecutive callback failures.
• A live strategy skips a failing update and stays enabled.
• After ten consecutive live strategy calculation errors, HyperionX suspends new entries while leaving exits and protection active.
• Historical and validation failures can abort the current run instead of using the live policy.

The strategy exposes AreEntriesSuspended, LastRuntimeError, ConsecutiveRuntimeErrors, and RuntimeStatusText. Do not call ResumeEntriesAfterFault() until the cause is corrected and account state is reconciled.

Recover from a bad build

If the project does not compile:

1. Read the first diagnostic.
2. Move only the suspect source completely outside the custom root.
3. Activate a clean build and verify the remaining project.
4. Restore the file and fix it before reactivation.

If runtime code misbehaves:

1. Disable the strategy or remove the chart object where possible.
2. Move the extension's owned source outside the custom root.
3. Build and activate an assembly without it.
4. Restart HyperionX if faulty in-process code left resources active.
5. Inspect logs before reintroducing the extension.

Source-checkout validation

Repository contributors can validate the live Code Lab folder with:

.\Scripts\compile-code-lab.bat

Bundled source also requires:

dotnet build .\HyperionX.Custom\HyperionX.Custom.csproj -c Release -p:Platform=x64

These commands are not required for installed users. Code Lab diagnostics are the first gate; successful desktop activation is the final gate.

Definition of done

• The full custom tree builds in Code Lab and activates in the desktop runtime.
• New warnings are understood.
• The type appears in its intended host.
• A fresh instance produces the written expected result.
• A second build proves reload and cleanup behavior.
• Historical, playback, simulation, and live differences are documented.
• Strategy code passes a simulation-first safety review.
• Logs contain no unexpected exceptions, credentials, account identifiers, or private data.