Oolite Bulletins

Posted: **Wed Jun 06, 2012 7:22 pm**

I am at the point where I am begining to look at using the debug console to check my OXPs and thought that it may be useful to have a thread in which anyone can ask questions relating to the debug console or for that matter post advice or some examples of the basic or most common commands.

I have copied below some initial information kindly provided by another_commander which outlines in brief what the debug console is for and where to download it.

another_commander wrote:
Shipbuilder wrote:
With regard to the console command how do i use this ?
The Debug Console is a must if you are doing OXP development or writing code for the core game. Using it lets you generate test conditions in the game in real-time in order to test OXPs, spawn ships you have created, change the AIs of entities on the fly, inject JavaScript code directly into the game and much more. It even allows for remote debugging sessions between two computers, where one is running the console and the other is running the game.

To enable it, you need to have Basic-debug.oxp installed in your AddOns folder. If you are using Windows, then Basic-debug.oxp is offered during installation of the game and by default it is installed, so unless you have changed the setting, you should have it already present.

Then you need to download the console program itself. It is found here: http://developer.berlios.de/project/sho ... e_id=18953.

To use it, you must run the OoDebugConsole.exe program before running Oolite. When run, the console window will open and report that it is waiting for connection. Starting up Oolite with the Basic-debug.oxp installed will establish this connection. From that point onwards, you can issue commands like the ones Thargoid mentioned earlier to the game via the console and see the responses/output in its window.

A simple search for "debug console" and "debug oxp" in the wiki yields some useful more in-depth information.

Thargoid’s commands noted above were: -
PS.target.AI
PS.target.AIState

Therefore in order to kick off the thread does anyone know what the command is to spawn a particular type of ship ?

Posted: **Wed Jun 06, 2012 7:31 pm**

The console has a number of built-in macros, which are useful to know (from debugConfig.plist, in the basic-debug.oxp):

Code: Select all

		"setM"		= "setMacro(PARAM)";
		"delM"		= "deleteMacro(PARAM)";
		"showM"		= "showMacro(PARAM)";
		"listM"		= "listMacro()";
		
		// Reload macros from plist, removing any custom ones.
		"resetM"	= "macros = console.settings.macros = {}; undefined";
		
		// Examining (“dumping”) objects
		"d"			= "dumpObject(eval(PARAM))";
		"proto"		= "consoleMessage('dumpObject', protoChain(eval(PARAM)))";
		
		// Clearing the console
		"clr"		= "console.clearConsole()";
		"clear"		= "console.clearConsole()";
		
		/*	For creating/testing colour sets. Syntax is flexible, as in plists,
			for example:
			:fgColor general "redColor"
			:bgColor command { hue: 60, saturation: 0.1 }
			:bgColor general [0, 0, 1, 1]
			
			rmFgColor/rmBgColor remove the specified setting from config
			overrides, returning to whatever is set in the plist.
		*/
		"fgColor"	= "setColorFromString(PARAM, 'foreground')";
		"bgColor"	= "setColorFromString(PARAM, 'background')";
		"rmFgColor"	= "void delete console.settings[PARAM + '-foreground-color']";
		"rmBgColor"	= "void delete console.settings[PARAM + '-background-color']";
		
		// ":nearest role" -- find nearest ship with specified role.
		// ":tnearest role" -- target nearest ship with specified role.
		"nearest"	= "this.result = system.shipsWithRole(PARAM, player.ship)[0]";
		"tnearest"	= "player.ship.target = system.shipsWithRole(PARAM, player.ship)[0]";
		
		// ":find expr" -- find entities matching expr; for example, ":find entity.isShip" to find all ships.
		// ":findS expr" -- find ships matching expr; for example, ":find ship.scanClass == 'CLASS_BUOY'".
		// ":target expr" -- target closest ship matching expr.
		"find"		= "this.result = system.filteredEntities(player.ship, function(entity) { return eval(PARAM); })";
		"findS"		= "this.result = system.filteredEntities(player.ship, function(ship) { return ship.isShip && eval(PARAM); })";
		"target"	= "player.ship.target = system.filteredEntities(player.ship, function(ship) { return ship.isShip && eval(PARAM); }, player.ship)[0]";
		
		// ":logOn className" -- enable logging for log message class className.
		// ":logOff className" -- disable logging for log message class className.
		"logOn"		= "console.setDisplayMessagesInClass(PARAM, true)";
		"logOff"	= "console.setDisplayMessagesInClass(PARAM, false)";
		
		// ":spawn foo" -- create a ship with role "foo" near the station.
		"spawn"		= "this.T = system.addShips(PARAM, 1, player.ship.position, 10000); if (this.T) this.T = this.T[0]; else consoleMessage('command-error', 'Could not spawn \"' + PARAM + '\".');";
		
		// ":qotd" -- quote of the day. Or the moment, anyway.
		"qotd"		= "expandDescription('[thargoid_curses]')";
		
		// ":test" -- display a ship of the specified role, assuming you're docked.
		"test"		= "mission.runScreen({model:PARAM})";
		
		// ":time <expression>" -- time a JavaScript expression.
		"time"		= "console.profile(eval(\"(function codeToBeProfiled() { (\" + PARAM + \") })\"), this)";
		
		// ":trace <expression>" -- trace a JavaScript expression.
		"trace"		= "console.trace(eval(\"(function codeToBeTraced() { (\" + PARAM + \") })\"), this)";

The item on the left of the equals is the macro name (used by a colon followed by the macro name, such as :spawn) with PARAM being the parameter passed to the macro.

So to answer the previous question, :spawn <role> will spawn a ship of role <role> within 10km of the player ship.

You can also define your own macros using the :setM command, delete them with :delM, list them with :listM and show the definition of one with :showM. For example to make a macro :dock to dock the player at the main station, you would use the command :setM dock S.mainStation.dockPlayer().[/color]

Posted: **Wed Jun 06, 2012 9:42 pm**

Shipbuilder wrote:
Thargoid’s commands noted above were: -
PS.target.AI
PS.target.AIState

There's no point in listing commands here. It's very simple: you can use each and every command of the JS-engine. In other words each and every command on each and every page that is listed here.

Shipbuilder wrote:
Therefore in order to kick off the thread does anyone know what the command is to spawn a particular type of ship?

Well, as said above, you can use all JS-commands. Therefore, in the debug console you use exactly the same commands that you would also use (or already have used) in a script. All ship spawning commands (there is—as you may know—more than one) are of course listed on the documentation page of the system-object.

Posted: **Wed Jun 06, 2012 11:58 pm**

Shipbuilder wrote:
Therefore in order to kick off the thread does anyone know what the command is to spawn a particular type of ship ?

I know what you mean, Shipbuilder. There is too much to know and you don't know where to start. I had that problem too. And still do!

SPOILER ALERT
Some of these commands WILL utterly remove any playability in the game. If you know you are the sort of person who will be tempted, do not read on. Seriously.
Note to moderators: by all means edit down this posting.

To get you started, here is some of my crib sheet:

Your own ship is [size=120]player.ship.[i]stuff[/i][/size] but that can be abbreviated to [size=120]PS.[i]stuff[/i][/size]
If you want to know about your ship, just enter [size=120]player.ship[/size]
Want its speed? [size=120]player.ship.speed[/size]
Fiddle with your cargo using PS.manifest.radioactives += 1 or [size=120]PS.manifest.alloys = 10[/size] et al e.g. gemStones and alienItems
Apply power-ups to your ship:

[size=120]PS.awardEquipment("EQ_HARDENED_MISSILE")

PS.awardEquipment("EQ_NAVAL_ENERGY_UNIT")

PS.awardEquipment("EQ_CLOAKING_DEVICE")

PS.awardEquipment("EQ_ENERGY_BOMB")

PS.awardEquipment("EQ_QC_MINE")

PS.awardEquipment("EQ_SHIELD_BOOSTER")

PS.awardEquipment("EQ_SHIELD_ENHANCER")[/size]

You are [size=120]player.[i]stuff[/i][/size] and you can edit your credits directly, and change your legal status by editing your bounty value. I would suggest you make a point of never doing this to your 'normal' commander and use a separate 'testing' commander.

Make a ship your target and you can refer to it via PS.target.[i]stuff[/i]
Change its legal status with [size=120]PS.target.bounty = [i]number[/i][/size]
What AI is that ship using? PS.target.AI
Change it with PS.target.setAI("minerAI.plist") or PS.target.setAI("route1traderAI.plist") et al.
What AI state is it in? PS.target.AIState
Change the state with PS.target.AIState = "FLEE" or PS.target.AIState = "COLLECT_STUFF" et al
Award the target with equipment: PS.target.awardEquipment("EQ_CLOAKING_DEVICE")
Clear the system of all ships: [size=120]system.sendAllShipsAway()[/size]

[size=120]system.legacy_addSystemShips("asteroid",8,0)[/size] will create 8 asteroids at the witchpoint (the zero)
system.legacy_addSystemShips("thargoid",2,1) will create 2 Thargoids at the station (the one)
system.legacy_addSystemShips("splinter",64,0.5) will create 64 (the maximum) asteroid splinters half way from the witchpoint to the station
You can specity 'police' or 'asteroid' or 'trader' or 'hunter' or 'station' or 'miner' or any other role)

Things to spoil your target's day:

PS.target.dumpCargo()

PS.target.abandonShip()

PS.target.exitSystem()

PS.target.explode()

Macro commands (these have a preceding ':') which create 1 (and only 1) object anywhere in your scanner range:

[size=120]:spawn asteroid

:spawn escort

:spawn hunter

:spawn interceptor

:spawn miner

:spawn pirate

:spawn police

:spawn trader

:spawn scavenger

:spawn sunskim-trader

:spawn wingman

:spawn thargoid

:spawn thargoid-mothership

:spawn cargopod

:spawn escape-capsule[/size]

The command to create a number of items near to you: system.addShips("miner",13,player.ship.position, 10000) creates 13 miners within 10km of you.

When you are bored, and have a fast PC, launch from the station and enter:
Shift-F (so you can see the number of entities as you want to keep this under 2000)

PS.awardEquipment("EQ_QC_MINE")

system.addShips("liner",64,player.ship.position, 10000)

system.addShips("liner",64,player.ship.position, 20000)

system.addShips("liner",64,player.ship.position, 30000)

Switch to rear view, drop the Q Bomb and inject out of there.
Stay on full speed and every 10 seconds or so enter
system.addShips("liner",64,player.ship.position, 20000)
and see how long you can keep the fireworks going before Oolite crashes, or you blow yourself up. It doesn't have to be 'liners' but they make the best flashes when they blow up, killing all 10,000 people on board.

)

Posted: **Thu Jun 07, 2012 3:45 am**

Thanks for posting the full macro list Thargoid - somehow I'd never actually looked at the file and wasn't aware of all of them....

Something I find it very useful for it testing that I'm getting the syntax and/or construction right for novel or complex JS commands - e.g construction of multi-dictionary Objects etc, or testing the output of some of the more esoteric native JS methods. I generally have Oolite running with my commander docked and the debug console open as I'm writing any script. It is much easier to tweak difficult JS syntax here and retest rather than getting the full script ready and running it through Oolite to spot problems.

Posted: **Thu Jun 07, 2012 7:29 am**

SandJ wrote:
[Some of these commands WILL utterly remove any playability in the game. If you know you are the sort of person who will be tempted, do not read on. Seriously.

You missed the poor mens docking computer:

Target a station and than type

Code: Select all

PS.target.dockPlayer()

Or the lazy trader that wants to skip the spacelane on system entry:

Code: Select all

S.mainStation.dockPlayer()

'S' can be used in the console as abbreviation of 'system'. Like the 'P' and 'PS" for 'player' and 'player.ship'

Posted: **Thu Jun 07, 2012 10:51 am**

What is the difference between Debug.oxp and Basic-Debug.oxp ?

And when both are installed, which should one keep? (The advice given is usually 'keep Basic-Debug' but Debug.oxp has more stuff within it.)

Posted: **Thu Jun 07, 2012 6:40 pm**

SandJ wrote:
What is the difference between Debug.oxp and Basic-Debug.oxp ?

And when both are installed, which should one keep? (The advice given is usually 'keep Basic-Debug' but Debug.oxp has more stuff within it.)

The difference between the two is that the Debug.oxp has stuff for Mac in it, like debugging menus and entity inspectors. The Mac version of the debug system is therefore a bit more advanced than the Windows/Linux ports' equivalent. Basic-debug.oxp is the bare-bones debug system supporting console functionality only.

If you are on Windows or Linux, then Basic-debug.oxp is just fine and is in fact what is included in the game's distribution for the test release configurations. Also, since the Basic-debug.oxp in Windows and Linux forms part of Oolite's package build sequence, it is guaranteed to be always current and compatible with the version of the game being run with. Running the current version of the game with a debug oxp made for an earlier version may result in unpredictable behaviour, usually manifested as sudden and inexplicable crashes.

Posted: **Sun Jun 10, 2012 1:30 pm**

Is it possible to call an OXP-defined function from the console? I've tried various naming formats at the console's command line, but all I'm getting is a "not defined" error.

Posted: **Sun Jun 10, 2012 1:39 pm**

Yes.

If it's in a worldScript:

Code: Select all

worldScripts["<scriptName>"].<functionName>

where <scriptName> is the name of the script (as defined in this.name at the top of it - not it's filename) and <functionName> is the name of the function. So for example to call the this.displayMessage function in the worldScript for Welcome Mat (this.name = "Welcome Information Script";) you would use

Code: Select all

worldScripts["Welcome Information Script"].displayMessage()

If it's in a ship script, you have to target (or some other way identify the given ship) and then use

Code: Select all

<ship>.script.<functionName>

where <ship> is the ship entity and the <functionName> is again the function, as above.

So for second example if the system main station has a script attached to it with a function launchMyShip, you would use:

Code: Select all

system.mainStation.script.launchMyShip()

You can use this command structure (the upper one) to reference one worldscript from another.[/color]

Posted: **Sun Jun 10, 2012 1:59 pm**

Code: Select all

 Object.keys(worldScripts)

will give you a handy list of all the worldScripts names in an array.

Similarly.

Code: Select all

Object.keys(worldScripts["Escort_Contracts"])

will list all of the properties (functions, variables and objects defined as this.xxx) of that named worldScript.

And you can even view the JS of a function without opening a text editor. Its the same syntax as calling it but without the brackets at the end.

Code: Select all

worldScripts["Escort_Contracts"].ec_contractsetup

From this you can then progress to online editing of functions with the game running to test syntax etc, although to be honest the console is a bit fiddly to do this on a wholesale basis.

Posted: **Sun Jun 10, 2012 2:13 pm**

Brilliant, thanks guys.

Posted: **Sun Jun 10, 2012 2:18 pm**

Code: Select all

Object.keys(missionVariables)

This one can be handy as-well to save you poking about in your save game.

Posted: **Sun Jun 10, 2012 2:24 pm**

As a passing comment - those aren't in the wiki lists.

I just learned something new today too - I knew this thread was a good idea

Posted: **Sun Jun 10, 2012 2:38 pm**

Thargoid wrote:
As a passing comment - those aren't in the wiki lists.

I just learned something new today too - I knew this thread was a good idea

I got those whilst idly trying out unfamiliar methods from https://developer.mozilla.org/en/JavaScript/Reference

The array of worldScripts could be very handy in script - if necessary you could loop through it looking for instances of a particular event handler and for example manually call that event handler in all scripts, or do various other unspeakable things....

Oolite Bulletins

Hints and tips for using the debug console

Hints and tips for using the debug console

Re: Hints and tips for using the debug console

Re: Hints and tips for using the debug console

Re: Hints and tips for using the debug console

Re: Hints and tips for using the debug console

Re: Hints and tips for using the debug console

Re: Hints and tips for using the debug console

Re: Hints and tips for using the debug console

Re: Hints and tips for using the debug console

Re: Hints and tips for using the debug console

Re: Hints and tips for using the debug console

Re: Hints and tips for using the debug console

Re: Hints and tips for using the debug console

Re: Hints and tips for using the debug console

Re: Hints and tips for using the debug console