@flamework-experimental/core 2.0.0-alpha.0

package/README.md

@@ -0,0 +1,66 @@
+# Flamework
+
+Flamework is an extensible framework for roblox-ts designed around portable, isolated and testable modules.
+
+## Documentation
+
+**[docs/](docs/README.md)** -- start there. A ten-part guide that builds up from a working entry
+point to plugins and project layout, plus reference material:
+
+| | |
+|---|---|
+| [Guide](docs/README.md#guide) | Getting started, modules, providers, lifecycle events, components, networking, macros, plugins, project structure, migrating from v1. |
+| [Internals](docs/reference/internals.md) | What the transformer does to your code and what the runtime does with the result. |
+| [Transformer plugins](docs/reference/transformer-plugins.md) | Adding macro types of your own. |
+
+The Flamework website documents v1, most of which no longer applies:
+
+https://flamework.fireboltofdeath.dev/docs/introduction
+
+## Development
+
+This repository is a [Bun](https://bun.sh) workspace. It also needs
+[Lune](https://lune-org.github.io/docs) on `PATH` to run the runtime specs.
+
+```sh
+bun install
+bun run build          # builds every package in dependency order
+bun run test           # build + transformer tests + runtime specs
+bun run lint
+```
+
+### Packages
+
+| Package | Description |
+|---|---|
+| `packages/core` | Modules, dependency injection, plugins and lifecycle events |
+| `packages/components` | CollectionService components, built on the core plugin system |
+| `packages/networking` | Remote events and functions |
+| `packages/testing` | In-place tests: sections, cleanup, a bindable and a remote to run them, a cloud entry; and `flamework-test`, the CLI that runs them in Roblox Studio on this machine or through Open Cloud (`cli/`) |
+| `packages/transformer` | The roblox-ts transformer |
+| `packages/transformer-plugin` | Public API for writing transformer plugins |
+| `packages/specs` | Runtime specs, compiled by `rbxtsc` and executed under Lune |
+
+### Tests
+
+Two suites, both run by `bun run test`:
+
+- **Transformer tests** (`bun run test:unit`) compile a fixture project with the real `rbxtsc` and
+  assert on the emitted Luau — guard generation, identifiers, nested macros and the plugin system.
+- **Runtime specs** (`bun run test:runtime`) execute compiled `@flamework-experimental/core`, `components` and
+  `networking` under Lune using the harness in [`tests/runtime`](tests/runtime), which models
+  roblox-ts's `TS.import` tree over the filesystem and stubs the Roblox API surface Flamework
+  touches (Instances, attributes, CollectionService, RemoteEvents, Players, signals, `task`,
+  `Enum`, and a `Heartbeat` pump so `Promise.delay` -- and therefore request timeouts -- runs).
+  They cover dependency injection, modules, hooks and the per-frame lifecycle events, component
+  construction, dependencies and streaming, and both halves of networking: events, functions,
+  middleware and the generated guards.
+
+  They run twice, once as `Server` and once as `Client`, because realm-dependent code paths --
+  `@Provider`'s metadata, component streaming, and the client/server halves of networking -- differ
+  between them. Where a spec asserts something realm-specific, running it from both sides is what
+  proves the two agree: a function receives on `$name` and sends on `@name` from the server and the
+  mirror image from the client, so the pair of runs pins the wire format down from both ends.
+
+Specs live in [`packages/specs`](packages/specs) and are compiled by `rbxtsc` like any other
+Flamework consumer, so they exercise the transformer and the runtime together.

package/flamework.build

@@ -0,0 +1,17 @@
+{
+	"version": 1,
+	"flameworkVersion": "2.0.0-alpha.0",
+	"identifiers": {
+		"@flamework-experimental/core:out/module/module@Module": "$:module/module@Module",
+		"@flamework-experimental/core:out/lifecycle/lifecyclePlugin@LifecycleProvider": "$:lifecycle/lifecyclePlugin@LifecycleProvider",
+		"@flamework-experimental/core:out/lifecycle/lifecyclePlugin@LifecyclePluginOptions": "$:lifecycle/lifecyclePlugin@LifecyclePluginOptions",
+		"@flamework-experimental/core:out/lifecycle/lifecycleInterfaces@OnInit": "$:lifecycle/lifecycleInterfaces@OnInit",
+		"@flamework-experimental/core:out/lifecycle/lifecycleInterfaces@OnStart": "$:lifecycle/lifecycleInterfaces@OnStart",
+		"@flamework-experimental/core:out/lifecycle/lifecycleInterfaces@OnTick": "$:lifecycle/lifecycleInterfaces@OnTick",
+		"@flamework-experimental/core:out/lifecycle/lifecycleInterfaces@OnRender": "$:lifecycle/lifecycleInterfaces@OnRender",
+		"@flamework-experimental/core:out/lifecycle/lifecycleInterfaces@OnPhysics": "$:lifecycle/lifecycleInterfaces@OnPhysics",
+		"@flamework-experimental/core:out/lifecycle/lifecycleInterfaces@OnExtinguished": "$:lifecycle/lifecycleInterfaces@OnExtinguished"
+	},
+	"idGenerationMode": "full",
+	"identifierPrefix": "$"
+}

package/out/dependency.d.ts

@@ -0,0 +1,18 @@
+import type { Modding } from "./modding";
+import type { Module } from "./module/module";
+/**
+ * Resolves a dependency from a module.
+ *
+ * Given a module, it resolves there. Otherwise it resolves from the default module: the first root
+ * module ignited in this realm, or the one ignited with `{ default: true }`.
+ *
+ * This is for code that has no constructor to inject through -- a UI component, a script, a callback
+ * handed to something outside Flamework. Inside a provider, take a constructor parameter instead:
+ * it declares the dependency where it can be read, and it orders construction.
+ *
+ * Raises if no module was given and none has been ignited yet, or if the default has since been
+ * extinguished.
+ *
+ * @metadata macro
+ */
+export declare function Dependency<T>(module?: Module, info?: string | Modding.Target.DependencyConcise<T>): T;

package/out/dependency.luau

@@ -0,0 +1,32 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local getDefaultModule = TS.import(script, script.Parent, "module", "defaultModule").getDefaultModule
+--[[
+	*
+	 * Resolves a dependency from a module.
+	 *
+	 * Given a module, it resolves there. Otherwise it resolves from the default module: the first root
+	 * module ignited in this realm, or the one ignited with `{ default: true }`.
+	 *
+	 * This is for code that has no constructor to inject through -- a UI component, a script, a callback
+	 * handed to something outside Flamework. Inside a provider, take a constructor parameter instead:
+	 * it declares the dependency where it can be read, and it orders construction.
+	 *
+	 * Raises if no module was given and none has been ignited yet, or if the default has since been
+	 * extinguished.
+	 *
+	 * @metadata macro
+	 
+]]
+local function Dependency(module, info)
+	if module == nil then
+		module = getDefaultModule()
+		if module == nil then
+			error("Dependency<T>() was called before any module was ignited", 2)
+		end
+	end
+	return module.resolveDependency(info)
+end
+return {
+	Dependency = Dependency,
+}

package/out/flamework.d.ts

@@ -0,0 +1,78 @@
+import { t } from "@rbxts/t";
+import { Modding } from "./modding";
+import { AbstractConstructor } from "./utility/constructors";
+import { ModuleBuilder } from "./module/moduleBuilder";
+import { PluginDefinition, type PluginTarget } from "./plugin/pluginDefinition";
+import { Serialization } from "./serialization/types";
+export declare namespace Flamework {
+    /**
+     * Creates a new Module which is the core functionality of Flamework.
+     *
+     * Every module starts with `LifecyclePlugin` included. `disableDefaultLifecycle()` on the builder
+     * leaves it out, and including one built with `createLifecyclePlugin` takes its place.
+     */
+    function createModule(): ModuleBuilder;
+    /**
+     * Creates a plugin: a setup function, run once per ignition of every module that includes it,
+     * which registers providers, hooks and observers into that module. See {@link PluginTarget} for
+     * what it can do. `name` labels the plugin in error messages.
+     */
+    function createPlugin(name: string, setup: (target: PluginTarget) => void): PluginDefinition;
+    /**
+     * The scopes this build is compiled with: `scopes.active` in `flamework.config.json`, which
+     * usually comes from the environment. `"*"` in the list stands for every scope.
+     */
+    function activeScopes(): readonly string[];
+    /**
+     * Whether a scope is active in this build. What an entry point asks before igniting a module
+     * that only exists for that scope.
+     */
+    function isScopeActive(scope: string): boolean;
+    /** @hidden */
+    function _implements<T>(object: unknown, id: string): object is T;
+    /**
+     * Retrieve the identifier for the specified type.
+     *
+     * @metadata macro {@link id intrinsic-inline}
+     */
+    function id<T>(id?: Modding.Target.Id<T>): string;
+    /**
+     * Inlines an environment variable at compile time: the call becomes the variable's value as a
+     * string literal, read from `.env`, `.env.local` and the process environment when the compiler
+     * started, or `undefined` when it is not set. With a fallback -- a string literal -- that is
+     * inlined instead, and the result is a `string`.
+     *
+     * For deployment values -- a place id, a build channel, a version -- and not for secrets: the
+     * value is written into the emitted Luau, where anyone with the place can read it.
+     *
+     * @metadata macro {@link value intrinsic-inline}
+     */
+    function env<N extends string, F extends string | undefined = undefined>(name: N, fallback?: F, value?: Modding.Intrinsic<"env", [N, F], F extends string ? string : string | undefined>): F extends string ? string : string | undefined;
+    /**
+     * Check if the constructor implements the specified interface.
+     *
+     * @metadata macro {@link _implements intrinsic-flamework-rewrite}
+     */
+    function implements<T>(object: AbstractConstructor, id?: Modding.Target.Id<T>): boolean;
+    /**
+     * Check if object implements the specified interface.
+     *
+     * @metadata macro {@link _implements intrinsic-flamework-rewrite}
+     */
+    function implements<T>(object: unknown, id?: Modding.Target.Id<T>): object is T;
+    /**
+     * Creates a type guard from any arbitrary type.
+     *
+     * @metadata macro
+     */
+    function createGuard<T>(meta?: Modding.Target.Guard<T>): t.check<T>;
+    /**
+     * Creates a serializer for `T`. The encode and decode code is generated from the type at compile
+     * time: plain `buffer` reads and writes, at constant offsets wherever the layout is fixed, with
+     * nothing describing the type left in the output. Instances and `unknown` values travel alongside
+     * the buffer as blobs.
+     *
+     * @metadata macro
+     */
+    function createSerializer<T>(meta?: Modding.Intrinsic<"serializer", [T], Serialization.Serializer<T>>): Serialization.Serializer<T>;
+}

package/out/flamework.luau

@@ -0,0 +1,138 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local Reflect = TS.import(script, script.Parent, "reflect").Reflect
+local ModuleBuilder = TS.import(script, script.Parent, "module", "moduleBuilder").ModuleBuilder
+local PluginDefinition = TS.import(script, script.Parent, "plugin", "pluginDefinition").PluginDefinition
+local LifecyclePlugin = TS.import(script, script.Parent, "lifecycle", "lifecyclePlugin").LifecyclePlugin
+local _scopes = TS.import(script, script.Parent, "module", "scopes")
+local getActiveScopes = _scopes.getActiveScopes
+local isScopeActiveInBuild = _scopes.isScopeActive
+local Flamework = {}
+do
+	local _container = Flamework
+	--[[
+		*
+		     * Creates a new Module which is the core functionality of Flamework.
+		     *
+		     * Every module starts with `LifecyclePlugin` included. `disableDefaultLifecycle()` on the builder
+		     * leaves it out, and including one built with `createLifecyclePlugin` takes its place.
+		     
+	]]
+	local function createModule()
+		return ModuleBuilder.new():setDebugName(2):includePlugin(LifecyclePlugin)
+	end
+	_container.createModule = createModule
+	--[[
+		*
+		     * Creates a plugin: a setup function, run once per ignition of every module that includes it,
+		     * which registers providers, hooks and observers into that module. See {@link PluginTarget} for
+		     * what it can do. `name` labels the plugin in error messages.
+		     
+	]]
+	local function createPlugin(name, setup)
+		return PluginDefinition.new(name, setup)
+	end
+	_container.createPlugin = createPlugin
+	--[[
+		*
+		     * The scopes this build is compiled with: `scopes.active` in `flamework.config.json`, which
+		     * usually comes from the environment. `"*"` in the list stands for every scope.
+		     
+	]]
+	local function activeScopes()
+		return getActiveScopes()
+	end
+	_container.activeScopes = activeScopes
+	--[[
+		*
+		     * Whether a scope is active in this build. What an entry point asks before igniting a module
+		     * that only exists for that scope.
+		     
+	]]
+	local function isScopeActive(scope)
+		return isScopeActiveInBuild(scope)
+	end
+	_container.isScopeActive = isScopeActive
+	--* @hidden 
+	local function _implements(object, id)
+		local _exp = Reflect.getMetadatas(object, "flamework:implements")
+		-- ▼ ReadonlyArray.some ▼
+		local _result = false
+		local _callback = function(impl)
+			local _impl = impl
+			local _id = id
+			return table.find(_impl, _id) ~= nil
+		end
+		for _k, _v in _exp do
+			if _callback(_v, _k - 1, _exp) then
+				_result = true
+				break
+			end
+		end
+		-- ▲ ReadonlyArray.some ▲
+		return _result
+	end
+	_container._implements = _implements
+	--[[
+		*
+		     * Retrieve the identifier for the specified type.
+		     *
+		     * @metadata macro {@link id intrinsic-inline}
+		     
+	]]
+	--[[
+		*
+		     * Inlines an environment variable at compile time: the call becomes the variable's value as a
+		     * string literal, read from `.env`, `.env.local` and the process environment when the compiler
+		     * started, or `undefined` when it is not set. With a fallback -- a string literal -- that is
+		     * inlined instead, and the result is a `string`.
+		     *
+		     * For deployment values -- a place id, a build channel, a version -- and not for secrets: the
+		     * value is written into the emitted Luau, where anyone with the place can read it.
+		     *
+		     * @metadata macro {@link value intrinsic-inline}
+		     
+	]]
+	--[[
+		*
+		     * Check if the constructor implements the specified interface.
+		     *
+		     * @metadata macro {@link _implements intrinsic-flamework-rewrite}
+		     
+	]]
+	--[[
+		*
+		     * Check if object implements the specified interface.
+		     *
+		     * @metadata macro {@link _implements intrinsic-flamework-rewrite}
+		     
+	]]
+	--[[
+		*
+		     * Creates a type guard from any arbitrary type.
+		     *
+		     * @metadata macro
+		     
+	]]
+	local function createGuard(meta)
+		return meta
+	end
+	_container.createGuard = createGuard
+	--[[
+		*
+		     * Creates a serializer for `T`. The encode and decode code is generated from the type at compile
+		     * time: plain `buffer` reads and writes, at constant offsets wherever the layout is fixed, with
+		     * nothing describing the type left in the output. Instances and `unknown` values travel alongside
+		     * the buffer as blobs.
+		     *
+		     * @metadata macro
+		     
+	]]
+	local function createSerializer(meta)
+		return meta
+	end
+	_container.createSerializer = createSerializer
+end
+return {
+	Flamework = Flamework,
+}

package/out/index.d.ts

@@ -0,0 +1,28 @@
+export { Flamework } from "./flamework";
+export { Modding } from "./modding";
+export { Reflect } from "./reflect";
+export { Provider } from "./provider";
+export { Injectable } from "./injectable";
+export { Dependency } from "./dependency";
+export { Serialization } from "./serialization/types";
+export type { ProviderDecoratorConfig } from "./provider";
+export type { InjectableDecoratorConfig } from "./injectable";
+export { ModuleDefinition } from "./module/moduleDefinition";
+export { ModuleBuilder } from "./module/moduleBuilder";
+export { HookPriority } from "./module/moduleHooks";
+export type { Module, ProviderLookup } from "./module/module";
+export type { IgniteOptions, InjectionContext, ModuleProvider, ModuleState, PluginInclusion, ProviderConfig, ProviderRegistrationOptions, } from "./module/moduleDefinition";
+export type { HookOptions } from "./module/moduleHooks";
+export { describeConditions, holdsCondition, holdsEveryCondition, __setActiveScopes } from "./module/scopes";
+export type { ScopeCondition } from "./module/scopes";
+export { PluginDefinition } from "./plugin/pluginDefinition";
+export { LifecyclePlugin, LifecycleProvider, createLifecyclePlugin } from "./lifecycle/lifecyclePlugin";
+export type { LifecyclePluginOptions } from "./lifecycle/lifecyclePlugin";
+export type { InterfaceConfiguration, InterfaceContext, InterfaceTargetKind, PluginTarget, } from "./plugin/pluginDefinition";
+export type { OnExtinguished, OnInit, OnPhysics, OnRender, OnStart, OnTick } from "./lifecycle/lifecycleInterfaces";
+export { getClassesInPath, importModule, requireModulesInPath } from "./utility/getClassesInPath";
+export { getClassesInGlob, getGlobPaths } from "./utility/globs";
+export { getPathRoot, resolveRbxPath, __setPathRoot } from "./utility/pathRoot";
+export { getRuntimeConfig } from "./utility/runtimeConfig";
+export type { ComponentsRuntimeConfig, CoreRuntimeConfig, NetworkingRuntimeConfig, RuntimeConfig, ScopesRuntimeConfig, TestingRuntimeConfig, } from "./utility/runtimeConfig";
+export type { AbstractConstructor, Constructor } from "./utility/constructors";

package/out/init.luau

@@ -0,0 +1,40 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local exports = {}
+exports.Flamework = TS.import(script, script, "flamework").Flamework
+exports.Modding = TS.import(script, script, "modding").Modding
+exports.Reflect = TS.import(script, script, "reflect").Reflect
+exports.Provider = TS.import(script, script, "provider").Provider
+exports.Injectable = TS.import(script, script, "injectable").Injectable
+exports.Dependency = TS.import(script, script, "dependency").Dependency
+-- Modules
+exports.ModuleDefinition = TS.import(script, script, "module", "moduleDefinition").ModuleDefinition
+exports.ModuleBuilder = TS.import(script, script, "module", "moduleBuilder").ModuleBuilder
+exports.HookPriority = TS.import(script, script, "module", "moduleHooks").HookPriority
+-- Scopes
+local _scopes = TS.import(script, script, "module", "scopes")
+exports.describeConditions = _scopes.describeConditions
+exports.holdsCondition = _scopes.holdsCondition
+exports.holdsEveryCondition = _scopes.holdsEveryCondition
+exports.__setActiveScopes = _scopes.__setActiveScopes
+-- Plugins
+exports.PluginDefinition = TS.import(script, script, "plugin", "pluginDefinition").PluginDefinition
+local _lifecyclePlugin = TS.import(script, script, "lifecycle", "lifecyclePlugin")
+exports.LifecyclePlugin = _lifecyclePlugin.LifecyclePlugin
+exports.LifecycleProvider = _lifecyclePlugin.LifecycleProvider
+exports.createLifecyclePlugin = _lifecyclePlugin.createLifecyclePlugin
+-- Lifecycle events
+-- Utilities that plugins need in order to implement path-based registration.
+local _getClassesInPath = TS.import(script, script, "utility", "getClassesInPath")
+exports.getClassesInPath = _getClassesInPath.getClassesInPath
+exports.importModule = _getClassesInPath.importModule
+exports.requireModulesInPath = _getClassesInPath.requireModulesInPath
+local _globs = TS.import(script, script, "utility", "globs")
+exports.getClassesInGlob = _globs.getClassesInGlob
+exports.getGlobPaths = _globs.getGlobPaths
+local _pathRoot = TS.import(script, script, "utility", "pathRoot")
+exports.getPathRoot = _pathRoot.getPathRoot
+exports.resolveRbxPath = _pathRoot.resolveRbxPath
+exports.__setPathRoot = _pathRoot.__setPathRoot
+exports.getRuntimeConfig = TS.import(script, script, "utility", "runtimeConfig").getRuntimeConfig
+return exports

package/out/injectable.d.ts

@@ -0,0 +1,13 @@
+export interface InjectableDecoratorConfig {
+}
+/**
+ * Marks a class as constructible through a module's dependency injection, without registering it as
+ * a provider.
+ *
+ * Use this for classes created with `Module.createClassInstance`: they get constructor injection
+ * and lifecycle events like a provider, but are not registered by `registerProviders` and cannot be
+ * resolved by id.
+ *
+ * @metadata reflect identifier flamework:dependencies flamework:implements flamework:parameters injectable
+ */
+export declare function Injectable(config?: InjectableDecoratorConfig): (constructor: object) => void;

package/out/injectable.luau

@@ -0,0 +1,23 @@
+-- Compiled with roblox-ts v3.0.0
+local TS = _G[script]
+local Reflect = TS.import(script, script.Parent, "reflect").Reflect
+--[[
+	*
+	 * Marks a class as constructible through a module's dependency injection, without registering it as
+	 * a provider.
+	 *
+	 * Use this for classes created with `Module.createClassInstance`: they get constructor injection
+	 * and lifecycle events like a provider, but are not registered by `registerProviders` and cannot be
+	 * resolved by id.
+	 *
+	 * @metadata reflect identifier flamework:dependencies flamework:implements flamework:parameters injectable
+	 
+]]
+local function Injectable(config)
+	return function(constructor)
+		Reflect.defineMetadata(constructor, "flamework:injectableConfig", config)
+	end
+end
+return {
+	Injectable = Injectable,
+}

package/out/lifecycle/lifecycleInterfaces.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Hook into the OnInit lifecycle event.
+ *
+ * `onInit` runs during ignition, after every provider has been constructed and before any `onStart`,
+ * in dependency order. It may return a Promise, which delays the initialisation of everything after
+ * it until the Promise settles; a rejection fails ignition.
+ *
+ * This is where setup that must be complete before other providers start belongs.
+ *
+ * A component implements it too. `Components` runs a component's `onInit` itself, synchronously,
+ * right after construction and before the component can be seen anywhere -- before `getComponent`
+ * hands it back, before another component receives it through a link, before an added listener
+ * hears of it. A Promise it returns is not waited for there, and a raise fails the construction.
+ */
+export interface OnInit {
+    /**
+     * Called once during ignition, in dependency order, before any `onStart`. On a component, once
+     * right after construction, before anything can see the component.
+     *
+     * Yielding or returning a Promise delays the providers after this one, so keep it short.
+     *
+     * @hideinherited
+     */
+    onInit(): void | Promise<void>;
+}
+/**
+ * Hook into the OnStart lifecycle event.
+ *
+ * A component implements it too: `Components` starts a component on its own thread once it is
+ * attached -- and not before ignition has finished, so one built during ignition starts once
+ * every provider has.
+ */
+export interface OnStart {
+    /**
+     * This function will be called after the current module has been initialized.
+     * This function will be called asynchronously.
+     *
+     * @hideinherited
+     */
+    onStart(): void;
+}
+/**
+ * Hook into the OnTick lifecycle event.
+ * Equivalent to: RunService.Heartbeat (the same point of the frame as PostSimulation in a running
+ * game, and it also fires in edit mode and in Open Cloud tasks, where PostSimulation does not).
+ */
+export interface OnTick {
+    /**
+     * Called every frame, after physics.
+     *
+     * @hideinherited
+     */
+    onTick(dt: number): void;
+}
+/**
+ * Hook into the OnPhysics lifecycle event.
+ * Equivalent to: RunService.PreSimulation
+ */
+export interface OnPhysics {
+    /**
+     * Called every frame, before physics.
+     *
+     * @param dt The time since the previous frame.
+     * @param time The elapsed game time, as returned by `time()`.
+     * @hideinherited
+     */
+    onPhysics(dt: number, time: number): void;
+}
+/**
+ * Hook into the OnRender lifecycle event.
+ * Equivalent to: RunService.PreRender
+ *
+ * @client
+ */
+export interface OnRender {
+    /**
+     * Called every frame, before rendering.
+     * Only fires on the client.
+     *
+     * @hideinherited
+     */
+    onRender(dt: number): void;
+}
+/**
+ * Runs when this module is terminated.
+ *
+ * It's not strictly required, but this can be convenient in code that must be run in tests or UI.
+ */
+export interface OnExtinguished {
+    /**
+     * Runs when this module is terminated.
+     */
+    onExtinguished(): void;
+}

package/out/lifecycle/lifecycleInterfaces.luau

@@ -0,0 +1,55 @@
+-- Compiled with roblox-ts v3.0.0
+--[[
+	*
+	 * Hook into the OnInit lifecycle event.
+	 *
+	 * `onInit` runs during ignition, after every provider has been constructed and before any `onStart`,
+	 * in dependency order. It may return a Promise, which delays the initialisation of everything after
+	 * it until the Promise settles; a rejection fails ignition.
+	 *
+	 * This is where setup that must be complete before other providers start belongs.
+	 *
+	 * A component implements it too. `Components` runs a component's `onInit` itself, synchronously,
+	 * right after construction and before the component can be seen anywhere -- before `getComponent`
+	 * hands it back, before another component receives it through a link, before an added listener
+	 * hears of it. A Promise it returns is not waited for there, and a raise fails the construction.
+	 
+]]
+--[[
+	*
+	 * Hook into the OnStart lifecycle event.
+	 *
+	 * A component implements it too: `Components` starts a component on its own thread once it is
+	 * attached -- and not before ignition has finished, so one built during ignition starts once
+	 * every provider has.
+	 
+]]
+--[[
+	*
+	 * Hook into the OnTick lifecycle event.
+	 * Equivalent to: RunService.Heartbeat (the same point of the frame as PostSimulation in a running
+	 * game, and it also fires in edit mode and in Open Cloud tasks, where PostSimulation does not).
+	 
+]]
+--[[
+	*
+	 * Hook into the OnPhysics lifecycle event.
+	 * Equivalent to: RunService.PreSimulation
+	 
+]]
+--[[
+	*
+	 * Hook into the OnRender lifecycle event.
+	 * Equivalent to: RunService.PreRender
+	 *
+	 * @client
+	 
+]]
+--[[
+	*
+	 * Runs when this module is terminated.
+	 *
+	 * It's not strictly required, but this can be convenient in code that must be run in tests or UI.
+	 
+]]
+return nil