Term

A term (short for terminal) is a standardised data structure in ComputerCraft. It describes anything that can be drawn to, e.g. the screen of a Computer, a Window, or an Advanced Monitor. All term objects must implement the same functions, but can also add their own.

Term functions

These functions are shared by all term objects.

Functionterm.blit
Writes text at the current cursor position in the current term, using foreground colors from textColour (a string containing colors as used in images loadable by paintutils functions) and background colors from backgroundColour (same as textColour). All characters represent a single hexadecimal digit which is then plugged into the equation c=2^(h-1) where h is the hexadecimal plugged in and c is a the equivalent color that would be plugged into term.setTextColor.
Syntax term.blit(
  • text : string
  • textColour : string
  • backgroundColour : string
)
Returns nil
Part of CC:Tweaked (source)
API term
ExamplePrint rainbow text
Prints "Hello world!" in 11-color text.
Code
<nowiki>
term.blit("Hello world!","01234456789a","f00000000000")
</nowiki>
Output Hello world!
Functionterm.clear
Clears the terminal object using the current background colour. The term's cursor position, text colour and background colour states remain unchanged.
Syntax term.clear()
Returns nil
Part of CC:Tweaked (source)
API term
ExampleClear a terminal
Clears the current term.
Code
<nowiki>
print("Hello, world!")
sleep(1)
term.clear()
    </nowiki>
Output Hello, world! is printed, and then disappears after 1 second.
ExampleClear a terminal with a colour
Clears the current term with a red background colour.
Code
<nowiki>
term.setBackgroundColour(colours.red)
term.clear()
    </nowiki>
Output The screen is cleared and filled with red.
Functionterm.clearLine
Clears the line on a terminal object using the current Y cursor position and background colour. The term's cursor position, text colour and background colour states remain unchanged.
Syntax term.clearLine()
Returns nil
Part of CC:Tweaked (source)
API term
ExampleClear a line
Writes a line, waits, and then clears it.
Code
<nowiki>
write("Hello, world!")
term.clearLine()
  </nowiki>
Output Hello, world! is printed, and then disappears after 1 second.
ExampleClear a specific line with a colour
Clears the top line of the current term with a red colour.
Code
<nowiki>
term.setBackgroundColour(colours.red)
term.setCursorPos(1, 1)
term.clearLine()
  </nowiki>
Output The top line of the screen is cleared and filled with red.
ExampleClear many lines with different colours
Draws a line which each colour to the screen, clearing everything between.
Code
<nowiki>
for i = 1, 16 do -- There are 16 colours.
  -- Colours in CC are a bitfield, so raising two to the power of n will give the nth colour.
  -- See </nowiki>[[Colours]]<nowiki> for more information.
  local colour = math.pow(2, i - 1) -- Subtract 1 as colours start from 0
  term.setBackgroundColour(colour)
  term.setCursorPos(1, i)
  term.clearLine()
end
  </nowiki>
Output
Functionterm.getBackgroundColour
Returns the numerical value of the current background colour of the terminal object.
Syntax term.getBackgroundColour()
Returns number colour
Part of CC:Tweaked (source)
API term
ExampleGet background colour
Prints the numerical value of the current term's background colour.
Code
<nowiki>
print(term.getBackgroundColour())
  </nowiki>
Output
32768
ExampleGet background colour name
Gets the current term's background colour, and then matches it against a lookup table to get its name.
Code
<nowiki>
local lookup = { 
    [1] = "white", [2] = "orange", [4] = "magenta", [8] = "lightBlue", 
    [16] = "yellow", [32] = "lime", [64] = "pink", [128] = "gray", 
    [256] = "lightGray",  [512] = "cyan", [1024] = "purple", [2048] = "blue", 
    [4096] = "brown",  [8192] = "green", [16384] = "red", [32768] = "black" 
}
local colour = term.getBackgroundColour()
print(lookup[colour])
  </nowiki>
Output
black
Functionterm.getCursorPos
Returns the current X and Y position of the cursor of the terminal object.
Syntax term.getCursorPos()
Returns number x, number y
Part of CC:Tweaked (source)
API term
ExampleGet cursor pos
Prints the cursor position of the current term.
Code
<nowiki>
local x, y = term.getCursorPos()
print(x, y)
  </nowiki>
Output
1, 3
Functionterm.getPaletteColour
Returns the RGB values (01) of the specified palette colour of the terminal object.
Syntax term.getPaletteColour(
  • colour : number
)
Returns number red, number green, number blue
Part of CC:Tweaked (source)
API term
ExampleGet specific palette colour
Prints the decimal RGB value of the colour red in the current term's palette.
Code
<nowiki>
local red, green, blue = term.getPaletteColour(colours.red)
print(red, green, blue)
  </nowiki>
Output 0.80000001192093 0.29803922772408 0.29803922772408 (equivalent to #cc4c4c)
ExampleGet current palette colour
Prints the decimal RGB value of the current term's text colour.
Code
<nowiki>
local colour = term.getTextColour()
local red, green, blue = term.getPaletteColour(colour)
print(red, green, blue)
  </nowiki>
Output 0.94117647409439 0.94117647409439 0.94117647409439 (equivalent to #f0f0f0)
Functionterm.getSize
Returns the width and height (in characters) of the terminal object.
Standard terminal sizes
Device Width Height
Computer 51 19
Turtle 39 13
Pocket Computer 26 20
Neural Interface 39 13
Syntax term.getSize()
Returns number width, number height
Part of CC:Tweaked (source)
API term
ExampleGet term size
Prints the width and height of the current term.
Code
<nowiki>
local width, height = term.getSize()
print(width, height)
  </nowiki>
Output On computers, 51 19
Functionterm.getTextColour
Returns the numerical value of the current text colour of the terminal object.
Syntax term.getTextColour()
Returns number colour
Part of CC:Tweaked (source)
API term
ExampleGet text colour
Prints the numerical value of the current term's text colour.
Code
<nowiki>
print(term.getTextColour())
  </nowiki>
Output
1
ExampleGet text colour name
Gets the current term's text colour, and then matches it against a lookup table to get its name.
Code
<nowiki>
local lookup = { 
    [1] = "white", [2] = "orange", [4] = "magenta", [8] = "lightBlue", 
    [16] = "yellow", [32] = "lime", [64] = "pink", [128] = "gray", 
    [256] = "lightGray",  [512] = "cyan", [1024] = "purple", [2048] = "blue", 
    [4096] = "brown",  [8192] = "green", [16384] = "red", [32768] = "black" 
}
local colour = term.getTextColour()
print(lookup[colour])
  </nowiki>
Output
white
Functionterm.isColour
Returns whether or not this terminal object supports colour.

This returns true for Advanced Computers, Advanced Turtles, Advanced Pocket Computers, Advanced Monitors and Neural Interfaces.

This returns false for Basic Computers, Basic Turtles, Basic Monitors and Basic Pocket Computers.
Syntax term.isColour()
Returns boolean
Part of CC:Tweaked (source)
API term
ExampleCheck if colour is supported
Prints whether or not the current term supports colour.
Code
<nowiki>
print(term.isColour())
  </nowiki>
Output
true
Functionterm.scroll
Moves everything on the screen up distance pixels.
Syntax term.scroll(
  • distance : number
)
Returns nil
Part of CC:Tweaked (source)
API term
ExampleMoves "Hello World!" up 3 pixels, and then prints "This text was printed 3 pixels below 'Hello World!"
Code
<nowiki>
term.clear()
term.setCursorPos(1,4)
print("Hello World!")
term.scroll(3)
print("This text was printed 3 pixels below 'Hello World!'")
    </nowiki>
Output
Hello World!



This text was printed 3 pixels below 'Hello World!'
Functionterm.setBackgroundColour
Sets the background colour of the terminal object. All text written after calling this function will have this background colour, until it is changed again.
Syntax term.setBackgroundColour(
  • colour : number
)
Returns nil
Part of CC:Tweaked (source)
API term
ExampleSet background colour
Prints "Hello, world!" with a green background.
Code
<nowiki>
term.setBackgroundColour(colours.green)
print("Hello, world!")
  </nowiki>
Output
Functionterm.setCursorBlink
Sets whether or not a blinking cursor should appear at the current cursor pos in the terminal object. When the cursor moves, the blinking cursor will move too, and it will continue to blink until it is manually turned off.
Syntax term.setCursorBlink(
  • blink : boolean
)
Returns nil
Part of CC:Tweaked (source)
API term
ExampleToggle blinking cursor
Lets the user press enter to toggle whether or not the cursor is blinking.
Code
<nowiki>
local blinking = false

print("Press enter to toggle whether or not the cursor is blinking.")
while true do
  local event, key = os.pullEvent("key")

  if key == keys.enter then
    blinking = not blinking -- Toggle blinking state.
    term.setCursorBlink(blinking)
    print("Blinking:", blinking)
  end
end
  </nowiki>
Output
Functionterm.setCursorPos
Sets the X and Y position of the cursor on the terminal object. The next write on this terminal object will begin from the new cursor position.
Syntax term.setCursorPos(
  • x : number
  • y : number
)
Returns nil
Part of CC:Tweaked (source)
API term
ExampleSet cursor pos
Clears the bottom line of the screen with a red colour, and prints "Hello, world!" in white text.
Code
<nowiki>
local width, height = term.getSize()

term.setBackgroundColour(colours.red)
term.setTextColour(colours.white)
term.setCursorPos(1, height - 1)
term.clearLine()
term.write("Hello, world!")
  </nowiki>
Output
Functionterm.setPaletteColour
Sets the RGB value of the specified palette colour of the terminal object. This allows you to change the appearance of all text and background using this colour.

The first argument is the colour that you want to change, e.g. colours.red. The arguments after that can either be:

  • An integer representing the hexadecimal RGB8 value of the colour, e.g. 0xFF0000 to produce the colour .
  • Three floats (01) representing the red, green and blue channels individually, e.g. 1.0, 0.0, 0.0 to produce the colour .
Syntax term.setPaletteColour(
  • colour : number
  • rgb : number
)

term.setPaletteColour(
  • colour : number
  • red : number
  • green : number
  • blue : number
)
Returns nil
Part of CC:Tweaked (source)
API term
ExampleUsing hex code
Changes the red colour from the default (#cc4c4c) to #FF0000.
Code
<nowiki>
term.setPaletteColour(colours.red, 0xFF0000)
term.setTextColour(colours.red)
print("Hello, world!")
  </nowiki>
Output
ExampleUsing separate RGB floats
Changes the red colour from the default (#cc4c4c) to #FF0000.
Code
<nowiki>
term.setPaletteColour(colours.red, 1, 0, 0)
term.setTextColour(colours.red)
print("Hello, world!")
  </nowiki>
Output
Functionterm.setTextColour
Sets the text colour of the terminal object. All text written after calling this function will have this colour, until it is changed again.
Syntax term.setTextColour(
  • colour : number
)
Returns nil
Part of CC:Tweaked (source)
API term
ExampleSet text colour
Prints "Hello, world!" in green.
Code
<nowiki>
term.setTextColour(colours.green)
print("Hello, world!")
  </nowiki>
Output
Functionterm.write
Writes text at the current cursor position in the current term. Unlike print, this function does not automatically move to the next line after writing. Additionally, unlike write and print, it does not perform any text wrapping.
Syntax term.write(
  • text : string
)
Returns nil
Part of CC:Tweaked (source)
API term
ExampleWrite to the term
Writes "Hello, world!" to the current term.
Code
<nowiki>
term.write("Hello, world!")
    </nowiki>
Output
Hello, world!
ExampleWrite multiple strings the term
Writes "foobar" to the current term. Note how there is no space between writes.
Code
<nowiki>
term.write("foo")
term.write("boo")
    </nowiki>
Output
foobar

Term events

Most of these events are shared by all term objects, but some, such as mouse events, are available exclusively for Advanced Interfaces.

Eventchar
Occurs every time the user typed a letter.
Returns
  • character : string The character the user typed
Part of CC:Tweaked
ExampleUsing char event
Ask a question that can be answered based on typing a character.
Code
<nowiki>
while true do
  print("Do you like pancakes? Press Y/N for yes or no.")

  local event, character = os.pullEvent("char")

  if character == "y" or character == "Y" then
    print("Great! I like pancakes aswell!")
    break
  elseif character == "n" or character == "N" then
    print("Ahw. Perhaps some soup then?")
    break
  else
    print("Sorry, but", character, "is not a valid answer!")
  end
end
    </nowiki>
Eventkey
Occurs every time the user presses down a key or when a key is being repeated because it's being held down.
Returns
  • keycode : number The keycode of the key being pressed
  • held : boolean Wether or not the key was already pressed earlier and is currently being held down
Part of CC:Tweaked
ExampleUsing key event
Showing what key the user is interacting with and telling if it's being held down.
Code
<nowiki>
while true do
  local event, key_code, being_hold = os.pullEvent("key")

  if being_hold then
    print("The player is holding", keys.getName(key_code), "down.")
  else
    print("The player pressed", keys.getName(key_code))
end
    </nowiki>
Eventkey_up
Occurs every time the user releases a previously pressed down key.
Returns
  • keycode : number The keycode of the key being released
Part of CC:Tweaked
ExampleUsing key_up event
Shows what key the player released.
Code
<nowiki>
while true do
  local event, key_code = os.pullEvent("key_up")

  print("The player released the", keys.getName(key_code), "key")
end
    </nowiki>
Eventmouse_click
Occurs every time a mouse button is pressed.  Note: This event is only called on advanced terms, such as an Advanced Computer, Advanced Pocket Computer or Neural Interface.
Returns
  • button : number The mouse button that was pressed
  • x : number The X position of the mouse in the term
  • y : number The Y position of the mouse in the term
Part of CC:Tweaked
ExamplePrint coordinates
Prints the mouse coordinates and button name every time a mouse button is pressed.
Code
<nowiki>
local button_names = { [1] = "left", [2] = "right", [3] = "middle" }

while true do
  local event, button, x, y = os.pullEvent("mouse_click")
  print("The", button_names[button], "mouse button has been pressed at", x, ",", y)
end
    </nowiki>
Eventmouse_drag
Occurs every time the mouse moves to a different position while a mouse button is held down (e.g. left click dragging). It will always be called after a mouse_click event.  Note: This event is only called on advanced terms, such as an Advanced Computer, Advanced Pocket Computer or Neural Interface.
Returns
  • button : number The mouse button that was pressed
  • x : number The X position of the mouse in the term
  • y : number The Y position of the mouse in the term
Part of CC:Tweaked
ExamplePrint coordinates
Prints the mouse coordinates every time the mouse is dragged on the screen.
Code
<nowiki>
while true do
  local event, button, x, y = os.pullEvent("mouse_drag")
  print("Dragged to:", x, y)
end
    </nowiki>
Eventmouse_scroll
Occurs every time a mousewheel scrolls.  Note: This event is only called on advanced terms, such as an Advanced Computer, Advanced Pocket Computer or Neural Interface.
Returns
  • direction : number The direction that was being scrolled in. -1 is up and 1 is down.
  • x : number The X position of the mouse in the term
  • y : number The Y position of the mouse in the term
Part of CC:Tweaked
ExamplePrint coordinates
Prints the scroll direction and mouse coordinates every time the user scrolled.
Code
<nowiki>
local scroll_directions = { [-1] = "up", [1] = "down" }

while true do
  local event, direction, x, y = os.pullEvent("mouse_scroll")
  print("The mousewheel scrolled", scroll_directions[direction], "at", x, ",", y)
end
    </nowiki>
Eventmouse_up
Occurs every time a mouse button is released after it was pressed down.  Note: This event is only called on advanced terms, such as an Advanced Computer, Advanced Pocket Computer or Neural Interface.
Returns
  • button : number The mouse button that was released
  • x : number The X position of the mouse in the term
  • y : number The Y position of the mouse in the term
Part of CC:Tweaked
ExamplePrint coordinates
Prints the mouse coordinates and button name every time a mouse button is released.
Code
<nowiki>
local button_names = { [1] = "left", [2] = "right", [3] = "middle" }

while true do
  local event, button, x, y = os.pullEvent("mouse_up")
  print("The", button_names[button], "mouse button has been released at", x, ",", y)
end
    </nowiki>
Eventpaste
Occurs every time the user pastes text into a terminal, with Ctrl-V
Returns
  • text : string The pasted text
Part of CC:Tweaked
ExampleUsing paste event
Printing everything the user pastes.
Code
<nowiki>
while true do
  local event, text = os.pullEvent('paste')
  print('Player pasted ' .. text)
end
    </nowiki>
ExampleUsing paste event
Saves everything that the user pastes to a file.
Code
<nowiki>
local f = fs.open("pasted_contents","w")
while true do
  local event, text = os.pullEventRaw()
  if event == 'paste' then
    f.writeLine(text)
  elseif event == 'terminate' then
    break
  end
end
f.close()
    </nowiki>
Eventterm_resize
Occurs every time the term resizes.
Returns
    nothing
Part of CC:Tweaked
ExampleNotify about resize
Notifies the user when the term has been resized.
Code
<nowiki>
while true do
  local event = os.pullEvent("term_resize")
  local x, y = term.getSize()
  print("The term has been resized to", x, ",", y)
end
    </nowiki>
This article is issued from Computercraft. The text is licensed under Creative Commons - Attribution - Sharealike. Additional terms may apply for the media files.