Table of Contents

Class RatatuiRenderer

Namespace
RatatuiUnity

MonoBehaviour that renders a Ratatui terminal to a UnityEngine.Texture2D and optionally assigns it to a UI UnityEngine.UI.RawImage or a MeshRenderer material each frame. When no target is assigned, falls back to OnGUI rendering. Use Full to stretch the terminal to the entire screen, Partial to draw at native pixel size with configurable alignment, or Window for a draggable macOS-style window whose title bar shows gameObject.name.

Override BuildFrame(RatatuiTerminal) to define widget layout. Override OnTerminalKeyDown(TerminalKeyEvent), OnTerminalMouseEvent(TerminalMouseEvent), and OnTerminalHoverChanged(TerminalHoverState, TerminalHoverState) to handle input events.

public class RatatuiRenderer : MonoBehaviour
Inheritance
Object
MonoBehaviour
RatatuiRenderer
Derived
Inherited Members

Properties

BackgroundColor

Terminal background color (alpha is ignored — texture is always opaque).

public Color BackgroundColor { get; set; }

Property Value

Color

Cols

Terminal width in character columns. Overridden by FitColsAndRows.

public int Cols { get; set; }

Property Value

int

EnableInput

Enable input processing (keyboard + mouse).

public bool EnableInput { get; set; }

Property Value

bool

EnableKeyboardInput

Enable keyboard input.

public bool EnableKeyboardInput { get; set; }

Property Value

bool

EnableMouseInput

Enable mouse input (hover, click, scroll).

public bool EnableMouseInput { get; set; }

Property Value

bool

FitColsAndRows

Derive cols × rows from the available pixel area (see field tooltip).

public bool FitColsAndRows { get; set; }

Property Value

bool

FontSize

Font size — interpretation depends on SizingMode.

public float FontSize { get; set; }

Property Value

float

HoverState

Current mouse hover state in terminal coordinates.

public TerminalHoverState HoverState { get; }

Property Value

TerminalHoverState

IsFocused

True if this renderer is the currently focused one. See RatatuiFocusManager.

public bool IsFocused { get; }

Property Value

bool

OnGuiDisplayMode

OnGUI display mode: Full, Partial, or Window.

public OnGuiMode OnGuiDisplayMode { get; set; }

Property Value

OnGuiMode

OnGuiHorizontalAlignment

Horizontal placement when OnGuiDisplayMode is Partial.

public OnGuiHorizontalAlign OnGuiHorizontalAlignment { get; set; }

Property Value

OnGuiHorizontalAlign

OnGuiVerticalAlignment

Vertical placement when OnGuiDisplayMode is Partial.

public OnGuiVerticalAlign OnGuiVerticalAlignment { get; set; }

Property Value

OnGuiVerticalAlign

Rows

Terminal height in character rows. Overridden by FitColsAndRows.

public int Rows { get; set; }

Property Value

int

SizingMode

How FontSize is interpreted (absolute pixels or viewport-relative).

public SizingMode SizingMode { get; set; }

Property Value

SizingMode

Terminal

The underlying terminal instance.

public RatatuiTerminal Terminal { get; }

Property Value

RatatuiTerminal

Texture

The rendered texture. Assign to any Unity material or UI image.

public Texture2D Texture { get; }

Property Value

Texture2D

WindowChromeFont

Font used for OnGUI window chrome (title bar + zoom / resize glyphs). Setter exists so renderers created via AddComponent at runtime — which skip Reset / OnValidate and therefore start with a null field — can have the bundled JetBrains Mono pushed in before Awake() finishes.

public Font WindowChromeFont { get; set; }

Property Value

Font

WindowInitialHeight

Initial window height in pixels including the title bar (Window mode). -1 = derive from terminal texture (Pixel sizing) or 70% of screen (Fit / viewport sizing).

public float WindowInitialHeight { get; set; }

Property Value

float

WindowInitialWidth

Initial window width in pixels (Window mode). -1 = derive from terminal texture (Pixel sizing) or 70% of screen (Fit / viewport sizing). Setting this also drives the FitColsAndRows target area on first open so the terminal grid matches.

public float WindowInitialWidth { get; set; }

Property Value

float

WindowStartMaximized

Start maximized (fills screen) on first open in Window mode.

public bool WindowStartMaximized { get; set; }

Property Value

bool

Methods

Awake() 

protected virtual void Awake()

BuildFrame(RatatuiTerminal)

Called every frame between BeginFrame and EndFrame. Override to define the terminal layout and widgets.

protected virtual void BuildFrame(RatatuiTerminal term)

Parameters

term RatatuiTerminal

FitRawImageToTexture()

Resizes the assigned RawImage's RectTransform to exactly match the terminal texture dimensions (1 texture pixel = 1 screen pixel at 100% scale). No-op when sizingMode is viewport-relative (Vh / Vw / Vmin / Vmax), since in those modes the RectTransform is the input to sizing and overwriting it would create a feedback loop.

public void FitRawImageToTexture()

ForceRefit()

Force an immediate refit + terminal recreation. Useful after manually changing the RawImage RectTransform from code, or after switching sizingMode.

public void ForceRefit()

OnDestroy() 

protected virtual void OnDestroy()

OnDisable() 

protected virtual void OnDisable()

OnEnable() 

protected virtual void OnEnable()

OnFocusChanged(bool)

Called when this renderer gains or loses scene focus. Override to react (e.g. update a visual). If overriding, call base.OnFocusChanged(isFocused) to keep the held-key reset that prevents stale key-repeat after focus loss.

protected virtual void OnFocusChanged(bool isFocused)

Parameters

isFocused bool

OnGUI() 

protected virtual void OnGUI()

OnRectTransformDimensionsChange()

Called by Unity whenever this GameObject's RectTransform (or a parent's) changes size. Used to mark the terminal for refit when sizingMode is a viewport-relative mode (Vh / Vw / Vmin / Vmax). Recreate is deferred to Update() because Unity disallows Destroy() from this callback.

protected virtual void OnRectTransformDimensionsChange()

OnTerminalHoverChanged(TerminalHoverState, TerminalHoverState)

Called when the hover state changes (mouse enters/exits areas or the terminal).

protected virtual void OnTerminalHoverChanged(TerminalHoverState oldState, TerminalHoverState newState)

Parameters

oldState TerminalHoverState
newState TerminalHoverState

OnTerminalKeyDown(TerminalKeyEvent)

Called for each keyboard event. Override to handle terminal key input.

protected virtual void OnTerminalKeyDown(TerminalKeyEvent e)

Parameters

e TerminalKeyEvent

OnTerminalMouseEvent(TerminalMouseEvent)

Called for mouse events (move, down, up, click, scroll). Override to handle terminal mouse input.

protected virtual void OnTerminalMouseEvent(TerminalMouseEvent e)

Parameters

e TerminalMouseEvent

RequestFocus()

Make this renderer the focused one. Equivalent to SetFocus(RatatuiRenderer).

public void RequestFocus()

SetCustomFont(byte[])

Replace the embedded JetBrains Mono font with a custom TTF font. Caches the bytes so subsequent terminal recreations (resize / DPI change) keep the user's font instead of falling back to the embedded default.

public bool SetCustomFont(byte[] ttfBytes)

Parameters

ttfBytes byte[]

Returns

bool

True if the font was loaded successfully.

TryGetTerminalCell(Vector2, out int, out int)

Converts a screen-space pixel position to terminal cell coordinates. Supports RawImage (UI), MeshRenderer (3D), and OnGUI fallback targets.

protected bool TryGetTerminalCell(Vector2 screenPos, out int col, out int row)

Parameters

screenPos Vector2
col int
row int

Returns

bool

Update() 

protected virtual void Update()

Events

OnCloseClicked

Fires when the user clicks the red close button in Window mode. While no subscribers are attached the button is rendered dim and ignores clicks (the default — closing an embedded window has no built-in meaning). Subscribe to enable the button: e.g. OnCloseClicked += () => SetOpen(false) on a RatatuiTerminalApp for toggle-style apps, or destroy / disable the GameObject for a hard close.

public event Action OnCloseClicked

Event Type

Action

OnTerminalResized

Fires after the terminal has been recreated due to a resize / DPI change. Args: new cols, new rows, new fontSize (px). Not fired for the initial Awake construction. Subscribers that cache Terminal, Texture, PixelWidth/PixelHeight, or cell metrics must refresh from the current values.

public event Action<int, int, float> OnTerminalResized

Event Type

Action<int, int, float>
Edit this page