bz2

The bz2 API provides access to the bzip2 library TPT bundles. It can be used for compressing and decompressing blocks of data, such as TPT saves.

Only one-shot functionality is exposed because streaming functionality is only useful for tasks that are beyond the scope of this API.

Unless stated otherwise, all functions raise errors if supplied with parameters that disagree with their descriptions.

bz2.compress

Compress data with bzip2 at compression level 9.

compressedData, errCode, errStr = bz2.compress(data, [maxSize])

• data: string, the data to be compressed
• maxSize: number, upper limit on the length of compressedData; defaults to 0, which means no limit
• compressedData: string, the compressed data, or nil on error
• errCode: nil, or one of the following values on error:
  • bz2.COMPRESS_NOMEM: out of memory, TPT will probably crash soon
  • bz2.COMPRESS_LIMIT: the length of compressedData would exceed maxSize
• errStr: nil, or a human-friendly string that explains the error

bz2.decompress

Decompress bzip2-compressed data.

data, errCode, errStr = bz2.decompress(compressedData, [maxSize])

• compressedData: string, the compressed data
• maxSize: number, upper limit on the length of data; defaults to 0, which means no limit
• data: string, the original data, or nil on error
• errCode: nil, or one of the following values on error:
  • bz2.DECOMPRESS_NOMEM: out of memory, TPT will probably crash soon
  • bz2.DECOMPRESS_LIMIT: the length of data would exceed maxSize
  • bz2.DECOMPRESS_TYPE: compressedData is not bzip2-compressed data
  • bz2.DECOMPRESS_BAD: compressedData is otherwise corrupt
  • bz2.DECOMPRESS_EOF: compressedData contains data beyond the end of the bzip2 stream
• errStr: nil, or a human-friendly string that explains the error

elements

The elements API contains methods and constants for creating and modifying elements.

The shorter alias elem is also available.

Unless stated otherwise, all functions raise errors if supplied with parameters that disagree with their descriptions.

elements.[group]_PT_[iname]

watrNumber = elements.DEFAULT_PT_WATR

There are two ways to refer to elements: element numbers and element identifiers, which are strings of the form "[group]_PT_[iname]". Both [group] and [iname] can be any string without underscores (_). All built-in elements are in group DEFAULT. For example, the identifier of WATR is "DEFAULT_PT_WATR", because WATR belongs to the group DEFAULT and its internal name is WATR. This is different from the Name property.

These constants map element identifiers to element numbers. The element number of WATR is 2, so elements.DEFAULT_PT_WATR is also 2.

elements.allocate

Create a new element.

elemNumber = elements.allocate(group, iname)

• group: string without underscores (_), the group the element belongs to; gets uppercased by the function
• iname: string without underscores (_), the internal name of the element; gets uppercased by the function
• elemNumber: the positive element number allocated for the element created, or -1 on error, if there are no free element numbers left

group should be something unique to your script, and should be the same across the entire script. It is common to use a simpler version of your username or the script’s name, for example if your script is called Ultimate Chemistry Pack v3, you might use "CHEMPACK3" as the group name.

iname should be unique to the element within your script, and should ultimately resemble the Name property of the element. For example, if your element’s name is C-6 you should use C6 as the internal name.

The resulting element identifier must be unique across all scripts in use at any point in time. Elements that seem like built-in elements, i.e. ones in the group DEFAULT, cannot be created. Note that, as stated above, both group and iname get uppercased, so elements.allocate("CheMpaCk3", "c6") is equivalent to elements.allocate("CHEMPACK3", "C6").

Make the choice such that it is convenient to refer to your element via an elements.[group]_PT_[iname] constant. While it is perfectly possible to type elem["Ultimate Chemistry Pack v3_PT_C-6"], it is much more convenient to type elem.CHEMPACK3_PT_C6.

The new element is created with all the default properties, and will not be visible until you modify it to show up in the menu.

elements.element

Query all or update multiple properties of an element.

elemProps = elements.element(elemNumber) -- query variant
elements.element(elemNumber, elemProps) -- update variant

• elemNumber: number of the element whose properties are to be queried or update
• elemProps: table that maps property names to property values

The keys and values of elemProps are the same as the propName and propValue parameters of elements.property. The query variant returns all properties of the element in elemProps with the same caveats as elements.property. The update variant accepts any subset of properties, only updates the ones present in the table, applying the same checks as elements.property.

This function is commonly used to base an element off another element by first copying all properties of the source element and applying them to the new element, and then customizing the new element a bit afterwards:

local purpleGold = elem.allocate("EXAMPLE", "PGLD")
assert(purpleGold ~= -1, "ran out of element numbers")
elem.element(purpleGold, elem.element(elem.DEFAULT_PT_GOLD))
elem.property(purpleGold, "Name", "PGLD")
elem.property(purpleGold, "Color", 0x8040FF)

elements.exists

Check whether a number is a real element number and refers to an element.

exists = elements.exists(elemNumber)

• elemNumber: number of the element to be checked
• exists: boolean, true if elemNumber refers to an element

If an element exists, there exists a corresponding elements.[group]_PT_[iname] constant, and conversely, if there exists such a constant, there exists a corresponding element.

elements.free

Free a previously allocated element.

elements.free(elemNumber)

• elemNumber: number of the element to be freed

The element number is freed and can used later by another script. Built-in elements, i.e. elements in the group DEFAULT, cannot be freed.

elements.getByName

Find an element by name, the Name property.

elementNumber = elements.getByName(name)

• name: string, the name to find the element by
• elemNumber: positive number of the element name refers to, or -1 on error if no such element exists

This function converts a human-friendly element name to an element number, essentially the same way the PROP tool or the console works.

elements.loadDefault

Restore the set of elements to its initial state at startup.

elements.loadDefault()

This frees all elements created and resets all properties of all built-in elements to their defaults.

elements.property

Query or update a property of an element.

propValue = elements.property(elemNumber, propName) -- query variant
elements.property(elemNumber, propName, propValue) -- update variant
elements.property(elemNumber, "Update", propValue, [runWhen]) -- special update variant for the Update property

• elemNumber: number of the element whose property is to be queried or updated
• propName: string, name of the property to be queried or updated
• propValue: various types, value of the property to be queried or updated
• runWhen: number, specifies when the update function should be run, one of:
  • elements.UPDATE_AFTER: run before the built-in update function, this is the default
  • elements.UPDATE_REPLACE: run instead of the built-in update function
  • elements.UPDATE_BEFORE: run after the built-in update function

The following table lists all element properties accessible via this function:

propName	propValue type	description
"Advection"	number
"AirDrag"	number
"AirLoss"	number
"CarriesTypeIn"	number
"ChangeType"	function	read-only
"Collision"	number
"Color"	number
"Create"	function	read-only
"CreateAllowed"	function	read-only
"CtypeDraw"	function	read-only
"DefaultProperties"	table
"Description"	string
"Diffusion"	number
"Explosive"	number
"Falldown"	number
"Flammable"	number
"Graphics"	function	read-only
"Gravity"	number
"Hardness"	number
"HeatConduct"	number
"HighPressure"	number
"HighPressureTransition"	element number
"HighTemperature"	number
"HighTemperatureTransition"	element number
"HotAir"	number
"Identifier"	string	element identifier, read-only
"Loss"	number
"LowPressure"	number
"LowPressureTransition"	element number
"LowTemperature"	number
"LowTemperatureTransition"	element number
"Meltable"	0 or 1
"MenuSection"	menu number
"MenuVisible"	0 or 1
"Name"	string	text that appears on the element button
"NewtonianGravity"	number
"PhotonReflectWavelengths"	number
"Properties"	number
"Temperature"	number
"Update"	function	read-only
"Weight"	number

runWhen is not possible to specify with elements.element.

event

event.getModifiers

event.register

event.unregister

fileSystem

fileSystem.copy

fileSystem.exists

fileSystem.isDirectory

fileSystem.isFile

fileSystem.isLink

fileSystem.list

fileSystem.makeDirectory

fileSystem.move

fileSystem.removeDirectory

fileSystem.removeFile

graphics

graphics.drawCircle

graphics.drawLine

graphics.drawPixel

graphics.drawRect

graphics.drawText

graphics.fillCircle

graphics.fillRect

graphics.getColors

graphics.getHexColor

graphics.setClipRect

graphics.textSize

constants

http

http.get

http.getAuthToken

http.post

interface

interface.activeMenu

interface.activeTool

interface.addComponent

interface.beginConfirm

interface.beginInput

interface.beginMessageBox

interface.beginThrowError

interface.brushID

interface.brushRadius

interface.button

interface.checkbox

interface.closeWindow

interface.console

interface.dropTextInput

interface.grabTextInput

interface.label

interface.menuEnabled

interface.mousePosition

interface.numMenus

interface.perfectCircleBrush

interface.progressBar

interface.removeComponent

interface.showWindow

interface.slider

interface.textInputRect

interface.textbox

interface.window

interface.windowSize

constants

platform

platform.clipboardCopy

platform.clipboardPaste

platform.exeName

platform.ident

platform.openLink

platform.platform

platform.releaseType

platform.restart

renderer

renderer.colorMode

renderer.debugHud

renderer.decorations

renderer.depth3d

renderer.displayModes

renderer.fireSize

renderer.grid

renderer.hud

renderer.renderModes

renderer.showBrush

renderer.useDisplayPreset

renderer.zoomEnabled

renderer.zoomScope

renderer.zoomWindow

simulation

simulation.addCustomGol

simulation.adjustCoords

simulation.airMode

simulation.ambientAirTemp

simulation.ambientHeat

simulation.ambientHeatSim

simulation.brush

simulation.canMove

simulation.clearRect

simulation.clearSim

simulation.createBox

simulation.createLine

simulation.createParts

simulation.createWallBox

simulation.createWallLine

simulation.createWalls

simulation.customGravity

simulation.decoBox

simulation.decoBrush

simulation.decoColor

simulation.decoLine

simulation.decoSpace

simulation.deleteStamp

simulation.edgeMode

simulation.elecMap

simulation.elementCount

simulation.fanVelocityX

simulation.fanVelocityY

simulation.floodDeco

simulation.floodParts

simulation.floodWalls

simulation.frameRender

simulation.getSaveID

simulation.golSpeedRatio

simulation.gravityField

simulation.gravityGrid

simulation.gravityMass

simulation.gravityMode

simulation.heatSim

simulation.historyForward

simulation.historyRestore

simulation.lastUpdatedID

simulation.listCustomGol

simulation.listStamps

simulation.loadSave

simulation.loadStamp

simulation.neighbors

simulation.newtonianGravity

simulation.partChangeType

simulation.partCount

simulation.partCreate

simulation.partExists

simulation.partID

simulation.partKill

simulation.partNeighbors

simulation.partPosition

simulation.partProperty

simulation.parts

simulation.paused

simulation.photons

simulation.pmap

simulation.pressure

simulation.prettyPowders

simulation.reloadSave

simulation.removeCustomGol

simulation.replaceModeFlags

simulation.resetGravityField

simulation.resetPressure

simulation.resetSpark

simulation.resetTemp

simulation.resetVelocity

simulation.saveStamp

simulation.signs

simulation.signs constants

simulation.signs[n]

simulation.signs.new

simulation.signs.delete

simulation.takeSnapshot

simulation.temperatureScale

simulation.toolBox

simulation.toolBrush

simulation.toolLine

simulation.updateUpTo

simulation.velocityX

simulation.velocityY

simulation.wallMap

simulation.walls

simulation.walls[id]

simulation.walls.'WL'

simulation.waterEqualization

constants

socket

socket.getTime

socket.sleep

socket.tcp

tpt

tpt.debug

tpt.drawCap

tpt.fpsCap

tpt.getUserName

tpt.installScriptManager

tpt.log

tpt.record

tpt.screenshot

tpt.version

Button

Button:action

Button:enabled

Button:position

Button:size

Button:text

Button:visible

Checkbox

Checkbox:action

Checkbox:checked

Checkbox:position

Checkbox:size

Checkbox:text

Checkbox:visible

Label

Label:position

Label:size

Label:text

Label:visible

ProgressBar

ProgressBar:position

ProgressBar:progress

ProgressBar:size

ProgressBar:status

ProgressBar:visible

Slider

Slider:onValueChanged

Slider:position

Slider:size

Slider:steps

Slider:value

Slider:visible

Textbox

Textbox:onTextChanged

Textbox:position

Textbox:readonly

Textbox:size

Textbox:text

Textbox:visible

Window

Window:addComponent

Window:onBlur

Window:onDraw

Window:onExit

Window:onFocus

Window:onInitialized

Window:onKeyPress

Window:onKeyRelease

Window:onMouseDown

Window:onMouseMove

Window:onMouseUp

Window:onMouseWheel

Window:onTick

Window:onTryExit

Window:onTryOkay

Window:position

Window:removeComponent

Window:size