Skip to content

Instantly share code, notes, and snippets.

What would you like to do?
Lets you teleport units; syntax is: number after unit is unit id, number after x,y,z is related position number, showunitid will show unit under cursor's ID, showpos will show position under cursor. Just a unit or just a position can be supplied; if either is the case, the cursor will be used to determine what the remaining variable is.
local function teleport(unit,pos)
local unitoccupancy = dfhack.maps.getTileBlock(unit.pos).occupancy[unit.pos.x%16][unit.pos.y%16]
unit.pos.x = pos.x
unit.pos.y = pos.y
unit.pos.z = pos.z
if not unit.flags1.on_ground then unitoccupancy.unit = false else unitoccupancy.unit_grounded = false end
local function getArgsTogether(args)
local settings={
for k,v in ipairs(args) do
if v=="unit" then settings.unitID=tonumber(args[k+1]) end
if v=="x" then settings.pos['x']==tonumber(args[k+1]) end
if v=="y" then settings.pos['y']==tonumber(args[k+1]) end
if v=="z" then settings.pos['z']==tonumber(args[k+1]) end
if v=="showunitid" then print(dfhack.gui.getSelectedUnit(true).id) end
if v=="showpos" then printall( end
if not settings.pos.x or not settings.pos.y or not settings.pos.z then settings.pos=nil end
if not settings.unitID and not settings.pos.x then qerror("Needs a position, a unit ID or both, but not neither!") end
return settings
local args = {...}
local teleportSettings=getArgsTogether(args)
local unit = teleportSettings.unitID and df.unit.find(teleportSettings.unitID) or dfhack.gui.getSelectedUnit(true)
local pos = teleportSettings.pos and teleportSettings.pos or

This comment has been minimized.

Copy link

hovissimo commented Jun 7, 2014

A friend and I are trying to use this, but we're not sure how to invoke showunitid. Is that a LUA function from somewhere else?


This comment has been minimized.

Copy link

draeath commented Feb 15, 2015

I can't get this to work. It doesn't do anything but throw tracebacks.

[DFHack]# teleport
...WARFF~1\Dwarf Fortress 0.40.24/hack/scripts/teleport.lua:7: attempt to index local 'unit' (a nil value)
stack traceback:
        ...WARFF~1\Dwarf Fortress 0.40.24/hack/scripts/teleport.lua:7: in function 'teleport'
        ...WARFF~1\Dwarf Fortress 0.40.24/hack/scripts/teleport.lua:41: in function 'f'
        ...ames\DWARFF~1\Dwarf Fortress 0.40.24\hack\lua\dfhack.lua:434: in function <...ames\DWARFF~1\Dwarf Fortress 0.
        (...tail calls...)
[DFHack]# teleport showpos
C:\Games\DWARFF~1\Dwarf Fortress 0.40.24\hack\lua\utils.lua:607: error parsing arg 1: showpos
stack traceback:
        [C]: in function 'error'
        C:\Games\DWARFF~1\Dwarf Fortress 0.40.24\hack\lua\utils.lua:607: in function 'processArgs'
        ...WARFF~1\Dwarf Fortress 0.40.24/hack/scripts/teleport.lua:29: in function 'f'
        ...ames\DWARFF~1\Dwarf Fortress 0.40.24\hack\lua\dfhack.lua:434: in function <...ames\DWARFF~1\Dwarf Fortress 0.
        (...tail calls...)

This comment has been minimized.

Copy link

NitinRao18 commented May 25, 2016

The way to use it is as follows. On DFHack window type, with the cursor on the unit in Dwarf Forttress
teleport -showunitid
It will display the unit id number say it is 9955.
Now in Dwarf fortress move the cursor to a safe new position and now type in DFHack
teleport 9955
this should save your Drowning Dwarf :-)


This comment has been minimized.

Copy link

Djent- commented May 30, 2016

I'd like to point out, playing in the most up to date version of the Lazy Noob Pack, I had to run

teleport -showunitid

and then

teleport -unit [result from -showunitid]

The documentation is not very useful and needs to be improved.


This comment has been minimized.

Copy link

lethosor commented Jul 29, 2016

You can't possibly be using this exact script, because this has several syntax errors that would make it unusable with any DFHack version (you wouldn't even get to the error you were seeing).

@Djent- there is somewhat-improved documentation at now.

If there continue to be issues with the teleport.lua script that's included in the most recent DFHack release (currently 0.43.03-r1), please open an issue at Thanks!

Also, you can find the current teleport script in the DFHack/scripts repo: (and you can suggest changes the documentation there).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.