Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/facepunch/sbox-public/llms.txt

Use this file to discover all available pages before exploring further.

Component is the abstract base class for all s&box game scripts. You attach components to GameObjects to give them behaviour. The engine calls lifecycle methods on your component at the right moment — OnAwake once at startup, OnEnabled and OnDisabled when the active state changes, OnUpdate every frame, and so on. This page documents every public and protected member you can override or use.
Your own components inherit from Component (or a subclass). You never instantiate Component directly — use go.AddComponent<T>() or go.GetOrAddComponent<T>().

​
Declaring a component

using Sandbox;

public sealed class MyComponent : Component
{
    [Property]
    public float Speed { get; set; } = 200f;

    protected override void OnAwake()
    {
        Log.Info($"Awake on {GameObject.Name}");
    }

    protected override void OnUpdate()
    {
        Transform.World = Transform.World.WithPosition(
            Transform.World.Position + Vector3.Forward * Speed * Time.Delta
        );
    }
}

​
Core properties

​
GameObject
GameObject
The GameObject this component belongs to. Accessing any component property before the component is attached (i.e. before the engine calls OnAwake) will give you null.
​
Scene
Scene
Shortcut for GameObject.Scene. The scene this component lives in.
​
Transform
GameTransform
Shortcut for GameObject.Transform. Position, rotation, and scale of the owning GameObject.
// Move the object upward every frame
Transform.World = Transform.World.WithPosition(Transform.World.Position + Vector3.Up * Time.Delta);
​
Components
ComponentList
Shortcut for GameObject.Components. The component list of the owning GameObject.
​
Tags
ITagSet
Shortcut for GameObject.Tags. The tag set of the owning GameObject.
​
Enabled
bool
The enable state of this component. Setting Enabled = false does not destroy the component — it pauses lifecycle callbacks. The component stays attached to the GameObject.
Enabled tells you what the component wants to be. Use Active to determine whether the component is actually ticking (i.e. the GameObject hierarchy is also enabled).
​
Active
bool
true when this component is enabled and all ancestor GameObjects are enabled. Only Active components receive OnUpdate, OnFixedUpdate, and similar callbacks.
​
IsValid
bool
true when this component is still attached to a GameObject and belongs to a scene. Returns false after Destroy() has been called.
​
Flags
ComponentFlags
Bitmask of ComponentFlags controlling serialisation and editor behaviour. See ComponentFlags.
​
Task
TaskSource
A TaskSource whose token is automatically cancelled when the component’s GameObject is disabled or destroyed. Use for async code that should stop cleanly.
protected override async void OnAwake()
{
    await Task.DelaySeconds(2f);
    if (!this.IsValid()) return; // cancelled if destroyed during wait
    Log.Info("2 seconds have passed");
}

​
Lifecycle methods

Lifecycle methods are called by the engine in a deterministic order. Override only what you need. 
Attached to active GameObject
       │
       ▼
    OnAwake()          ← called once, on first activation
       │
       ▼
    OnEnabled()        ← called when becoming active
       │
       ▼
    OnStart()          ← called before the first OnUpdate()
       │
┌──────┴──────┐
│             │
▼             ▼
OnUpdate()   OnFixedUpdate()   ← called each frame / fixed step
(every frame) (fixed interval)
│
▼
OnPreRender()          ← called before the scene is rendered
│
▼
OnDisabled()           ← called when becoming inactive
│
▼
OnDestroy()            ← called once when destroyed

​
OnAwake

protected virtual void OnAwake()
Called exactly once, the first time this component becomes active. Use it for one-time initialisation that requires the GameObject and scene to be present — equivalent to a constructor, but with the guarantee that the scene is ready.
OnAwake fires before OnEnabled. If you disable a component and re-enable it, OnEnabled fires again but OnAwake does not.

​
OnEnabled

protected virtual void OnEnabled()
Called each time this component transitions from inactive to active. This includes the initial activation after OnAwake. Use it to register for events, start coroutines, or set up state that must be torn down in OnDisabled.

​
OnStart

protected virtual void OnStart()
Called once before the first OnUpdate, after OnEnabled. Runs at the start of the first frame the component is active. Use it for logic that depends on other components having completed their OnAwake and OnEnabled calls.

​
OnUpdate

protected virtual void OnUpdate()
Called every frame while the component is active. Time.Delta gives the elapsed seconds since the last frame. Not called on dedicated servers. 
protected override void OnUpdate()
{
    // Rotate 90 degrees per second around the up axis
    Transform.World = Transform.World.WithRotation(
        Transform.World.Rotation * Rotation.FromAxis(Vector3.Up, 90f * Time.Delta)
    );
}

​
OnFixedUpdate

protected virtual void OnFixedUpdate()
Called at a fixed time step matching the physics simulation rate. Time.Delta is the fixed step duration. Use for physics manipulation and anything that must be framerate-independent. 
protected override void OnFixedUpdate()
{
    // Apply force in physics step
    var rb = GetComponent<Rigidbody>();
    rb?.ApplyForce(Vector3.Up * 500f);
}

​
OnPreRender

protected virtual void OnPreRender()
Called once per frame before the scene is rendered, while the component is active. Not called on dedicated servers. Use it to update scene objects (e.g. SceneModel) that must be in sync with transforms before the draw call.

​
OnDisabled

protected virtual void OnDisabled()
Called each time this component transitions from active to inactive. Mirror OnEnabled — tear down anything set up there (event subscriptions, etc.).

​
OnDestroy

protected virtual void OnDestroy()
Called once, just before this component is detached from its GameObject and discarded. After this method returns, IsValid is false.

​
OnValidate

protected virtual void OnValidate()
Called after deserialization and when a [Property] is changed in the editor. Use it to clamp values, recalculate derived state, or update visual representations in response to property edits.

​
OnParentChanged

protected virtual void OnParentChanged(GameObject oldParent, GameObject newParent)
Called when the parent GameObject changes. Useful for components that cache a reference to the parent or need to adjust their state based on hierarchy position.

​
OnParentDestroy

public virtual void OnParentDestroy()
Called when the parent GameObject is being destroyed. Override to re-parent or clean up before the parent disappears.

​
OnTagsChanged

protected virtual void OnTagsChanged()
Called whenever tags on this GameObject or any ancestor change.

​
Invoke (delayed callback)

public async void Invoke(float secondsDelay, Action action, CancellationToken ct = default)
Calls action after secondsDelay seconds. The callback is silently dropped if the component is no longer active or the CancellationToken is cancelled. 
// Self-destruct after 5 seconds
protected override void OnAwake()
{
    Invoke(5f, () => GameObject.Destroy());
}

​
Component access shortcuts

All of these are convenience wrappers around Components. See GameObject — component methods for the full parameter documentation; the signatures are identical. 
public T AddComponent<T>(bool startEnabled = true) where T : Component, new()
public T GetOrAddComponent<T>(bool startEnabled = true) where T : Component, new()
public T GetComponent<T>(bool includeDisabled = false)
public IEnumerable<T> GetComponents<T>(bool includeDisabled = false)
public T GetComponentInChildren<T>(bool includeDisabled = false, bool includeSelf = true)
public IEnumerable<T> GetComponentsInChildren<T>(bool includeDisabled = false, bool includeSelf = true)
public T GetComponentInParent<T>(bool includeDisabled = false, bool includeSelf = true)
public IEnumerable<T> GetComponentsInParent<T>(bool includeDisabled = false, bool includeSelf = true)

​
Destroying a component

​
Destroy

public void Destroy()
Removes this component from its GameObject. OnDisabled then OnDestroy are both called. After this call, IsValid returns false.
Destroy() only removes the component, not the entire GameObject. To destroy the GameObject, call DestroyGameObject() or GameObject.Destroy().

​
DestroyGameObject

public void DestroyGameObject()
Convenience shortcut for GameObject?.Destroy(). Destroys the owning GameObject and all of its children and components.

​
ComponentFlags

ComponentFlags is a bitmask you can set on component.Flags to control engine behaviour.
​
Hidden
flag
Hides this component in the editor’s component inspector.
​
NotSaved
flag
This component is not serialised to disk when the scene is saved.
​
NotNetworked
flag
This component is excluded from the networked scene snapshot.
​
NotCloned
flag
This component is skipped when the GameObject is cloned via Clone().
​
ShowAdvancedProperties
flag
Shows advanced (normally hidden) properties in the component inspector.
// Mark a component as hidden and non-serialised
component.Flags = ComponentFlags.Hidden | ComponentFlags.NotSaved;

​
Action Graph event hooks

The following [Property] callbacks let you wire Action Graph nodes directly to component events without subclassing:
PropertyFires when
OnComponentEnabledComponent becomes active
OnComponentStartFirst frame after becoming active
OnComponentUpdateEvery frame while active
OnComponentFixedUpdateEvery physics step while active
OnComponentDisabledComponent becomes inactive
OnComponentDestroyComponent is destroyed

​
See also

GameObject

The object that components attach to.

Scene

The scene container; use Scene.GetAll<T>() to find components across the whole scene.

Scripting basics

Practical guide to writing and attaching components.

Build docs developers (and LLMs) love

Get started for freeTalk to us