What to use when

The package offers more than one way to do most things. This page picks between them; each answer links to the page that covers it.

What drives the screen

You want	Use
A telnet host, such as a MUD or a BBS	TelnetConnection
A service that speaks plain lines over TCP, such as a MUD or a server of your own	TcpConnection
A network host from a WebGL build	WebSocketConnection, through a relay
A command line program on a server, such as a shell or a curses game	TtydConnection
A shell, a console, or a text game of your own, with a prompt and scrolling output	ITerminalProgram through LocalProgramConnection
A full-screen interface of menus, lists, and gauges	TerminalUI, see below
A full-screen display you draw cell by cell, such as a map or a waveform	ISurfaceProgram through session.RunSurface
Lines printed from game code, with nothing to type at	session.Emulator.FeedText
An operating-system shell on the same machine, or a serial port	Your own ITerminalConnection
A working terminal to test a scene with	Start Demo Shell on the session

Connections covers the first five and the last two. Interfaces covers interfaces and surface programs.

Terminal program or surface program

Both run in your process. An ITerminalProgram writes escape sequences and reads bytes, as a remote host does. An ISurfaceProgram writes cells and receives events.

	ITerminalProgram	ISurfaceProgram
Output	Escape sequences, parsed by the emulator	Cells, drawn as they are
Scrollback, selection, and copy	Yes	No
The terminal’s cursor	Yes	No
Input	Bytes; AnsiInputDecoder turns them into events	Events, with key releases and hover
Live textures	Overlays you place yourself	Named slots, bound on the session
Runs over a network connection	Yes, the same code serves a remote terminal	No
Suits	Line-oriented output, ported terminal programs	Anything that redraws every frame

Choose a terminal program when the output scrolls and a player may select it, or when the same program should run for a remote client. Choose a surface program when the whole screen is yours and it animates.

A surface program runs over the terminal, which shows again when it exits. A shell command that opens a full-screen display is a terminal program that calls session.RunSurface; the demo shell’s ui command does this.

How to run an interface

A TerminalUI runs either way with no change to the element tree.

	UISurfaceProgram	UIAnsiProgram
Start it with	session.RunSurface	session.SetConnection and a LocalProgramConnection
Animation every frame	Cheap	Costs a parse of every changed cell
TextureView	Shows the texture	Shows the slot’s name
Runs in any terminal, through any connection	No	Yes

Use UISurfaceProgram in a game. Use UIAnsiProgram when the interface has to reach a terminal outside this session.

Where it shows

You want	Use
A screen on an object in the scene	Terminal Screen (3D)
A panel in a canvas, or a terminal that fills the window	Terminal Screen (UI)
The same terminal in both places	One session, two screens
The picture in a Shader Graph material, behind glass or on a modeled monitor	Terminal Screen (3D) and the Terminal Screen sub graph
The picture in a shader or a script of your own	A screen’s DisplayTexture, with the screen type applied, or session.Renderer.Target, the bare grid
No picture, emulation only	TerminalEmulator on its own

How big it is

Three sizes are separate: the grid in columns and rows, the cell size in pixels, and the surface the picture is shown on. Grid, render, and display size explains them.

You want	Set
A fixed grid, such as 80 by 24, on a scene screen	Columns and Rows on the session, and Resolution on the screen
A column count you choose, with rows that fill the screen’s shape	Resolution and Fit Rows on the screen; change columns with session.SetSize
A fixed grid scaled to fit a canvas panel	Scale mode Fit In Parent
A fixed grid at one texture pixel per display pixel	Scale mode Native Pixels
A terminal that fills the window and gains columns and rows as the window grows	Terminal Viewport Fitter
A RectTransform your own layout controls	Scale mode Manual
Larger or smaller text during play	session.SetFontSize

Give one screen per session a Resolution or a fitter. Both set the session’s font size, so two of them on one session contend.

How it looks

You want to change	Edit
The font, the colors, the palette, or the cursor	The Terminal Theme on the session
Scanlines, curvature, glow, tint, or filtering	The Terminal Screen Type on the screen
The surface around the picture: glass, reflections, a housing	A material of your own with the Terminal Screen sub graph

A theme belongs to the session, so every screen of that session shares it. A screen type belongs to one screen, so a CRT on a desk and a flat panel can show the same session.

For a flat view, leave the screen type empty or use Flat, with the Point filter. For a curved or distant screen, use a CRT preset, which filters Bilinear; Green CRT and Amber CRT curve the picture, and Color CRT keeps it flat. Themes and screen types covers every setting.

How a screen behaves during play

A look is fixed in an asset. What happens to one screen at run time is a call on that screen.

You want	Use
A monitor that switches on or off, with a tube collapse or a cut	screen.PowerOn() and screen.PowerOff()
The classic off and back on	screen.PowerCycle()
A picture that rolls, then locks again	screen.LoseVerticalHold and screen.RecoverVerticalHold, or screen.RollOnce
A signal that is always a little rough	screen.Signal = SignalCondition.Noisy(0.1f)
A moment of breakup on a story beat	screen.Glitch(seconds, strength), or screen.Play with a cue of your own
A panel cracked where something hit it	screen.Damage, by picture position, cell, ray, or world point
The same cracks after loading a save	Keep screen.Display.impacts, and pass each back to screen.Damage
Everything back to normal at once	screen.ResetBehaviors()
The screen to light the room around it	A Terminal Screen Light on a Light in front of the glass

Each screen holds its own state, so one of two screens showing a session can be off, or cracked, while the other is fine. Screen behaviors covers them.

How to show a picture

You want	Use
An image over part of the terminal	session.Renderer.AddOverlay
An image under text that labels it	An overlay with BehindText
A camera feed or a video	An overlay with Live, or a TextureView
A texture placed by an interface’s layout	TextureView and session.BindTexture
Labels, brackets, or a reticle drawn over that texture	Draw on the TextureView
A shape drawn from characters inside an interface	Paint
Drawing of your own into the grid texture	session.Renderer.AfterRender

Overlays take a cell rectangle you compute. A TextureView takes its rectangle from layout and moves with it, and needs a surface program.

How to draw large text

You want	Use
A banner inside an interface	BigText
A banner printed into a shell or a terminal program	FigletFontAsset.Render, written a row at a time
Control of spacing, direction, or wrapping	FigletText

How to share the keyboard with a game

The game needs	Use
The terminal to stop typing when the player clicks away	Release Focus On Outside Click
Typing paused during a menu or a cutscene, with focus kept	session.AcceptsKeyboard = false
One key for itself while the terminal has focus	session.SkipKeyboardThisFrame()
Focus moved by game logic, such as sitting down at a desk	session.Focus() and session.Blur()

How to send input from something else

The source is	Use
A script that types text	session.SendText
A gamepad or an on-screen keyboard	session.Send with InputEncoder.Key
An XR controller or an in-game cursor	PointFromRay, ButtonFromRay, and ScrollFromRay on the scene screen
The mouse, over a screen in the scene or in a canvas	Nothing to add; each screen reads it

Input and selection covers all of these.