Debugging Scripts

From Avorion Wiki
Jump to: navigation, search

Lua scripts that run in Avorion rely heavily on the Avorion Scripting API and thus aren't easy to debug in normal lua environments. Avorion provides a range of methods you can use to debug them more easily though.

'~dev' debug Script[edit | edit source]

You can add the debug script to your current craft by using the following chat command:

/run Entity():addScript("lib/entitydbg.lua")

This adds a new ~dev interaction to that entity which opens a large menu that allows you to manipulate nearly everything in the sector and your inventory, and, most importantly: It allows you to view and modify variables and scripts of entities, players, sectors and so on.

This script is meant to ease development and debugging of mods in general, so use it!

'print' debugging[edit | edit source]

An easy way to debug scripts is to add regular calls to print() or eprint() while writing your script. You can open the in-game console with a button.

Note: The in-game console isn't configured to a working button by default, you will have to configure it manually yourself.

  • print() will print regular output to the console
  • eprint() will print error output to the console

Depending on where the function was executed, the output will have different colors in the console, making it easy to distinguish client-prints from server-prints. Please consult the Scripting API for more information to these functions.

printTable()[edit | edit source]

Use the printTable() function to recursively print a table. It's defined in data/scripts/lib/utility.lua.

Logging[edit | edit source]

Another easy way to debug scripts, mostly while they're being used by players already, is to use logging. You can use the printlog() function, that behaves similarly to print(), but prints to the logfile instead of the console. Depending on whether that function is called on the client or server, it will print to the client or server logfile.

type()[edit | edit source]

Use type() to find out what kind of object you're dealing with. type() is a built-in lua function that can display the type of an object.

local a = 2
local b = "foo"

print (type(a))
print (type(b))

Output:

number
string

Note: type() will always display userobject for Avorion Scripting API objects. See __avoriontype below.

__avoriontype[edit | edit source]

All Avorion Scripting API objects have a "secret" __avoriontype property, that is basically just a string containing their internal avorion type.

You can use this property to easily

  • find out if the instance is a Scripting API object
  • find out what type the object has exactly
local m = Matrix()
print (type(m))
print (m.__avoriontype)

Output:

userobject
Matrix

/devmode[edit | edit source]

When typing in the command /devmode, the game goes into development mode. In order for development mode to be properly initialized, a restart is required.

The following functionality is only available in /devmode and not meant to be user-friendly in any way. Its only purpose is to speed up development.

entitydbg.lua on each entity[edit | edit source]

In /devmode, each Entity that can have scripts, will have the entitydbg.lua script attached to it.

F5 / F6[edit | edit source]

Please note: This feature is not polished in any way and can (will...) crash the game on occasion.

  • F5: Reload scripts of selected Entity (if any)
  • F5: Reload scripts of current Sector (if no Entity selected)
  • Shift-F5: Reload scripts of Player
  • Ctrl-F5: Reload scripts of Sector and all Entities
  • F6: Clear scripts cache of all client-side scripts (mod files, tooltips, parts, upgrades, sectorspecs, fighter templates)
  • Ctrl-F6: In addition to normal F6, also reload shaders, textures and client config (this might crash the client if done too often)
  • Shift-F7: Cycle through various background rendering variations and textures
  • F11: Reload volumes.ini

Pitfalls[edit | edit source]

Sadly, the Avorion Scripting API and its environment comes with a few pitfalls that you simply have to be aware of to avoid them.

You can read more about Modding Pitfalls here.

See Also[edit | edit source]