Elite Wiki - User contributions [en]

Viewing a Texture or Model

2009-11-21T06:29:40Z

Captain Berf:

== How to view a specific model and / or texture in Oolite. ==

===Using the in-game external views===

If the ship you want to view is your player ship simply launch the ship and press v to cycle through the external views.
Otherwise ...

----

===Install Debug.oxp===

1. Add Debug.oxp to your Oolite AddOns [http://wiki.alioth.net/index.php/Debug_OXP]
-- Extract the archive.
-- Move the extracted folder Debug.oxp to $PROGDIR/AddOns/
2. Install PyDebugConsole [https://developer.berlios.de/project/showfiles.php?group_id=3577]
-- Extract the archive
-- Put the directory OODebugConsole wherever you like

===Run Oolite with the DebugConsole===

1. Run the DebugConsole [WhereverIPutIt/OODebugConsole/OODebugConsole.exe]
2. Start Oolite
(If you have modified an oxp hold down the shift key during during the boot
to clear the cache)
3. Launch into space [Press 1](moving into a clear area helps).

===Spawning the ship you want to view actively in the game===

====Spawning the ship====

Type in the console

:spawn ''shipUniqueRole''

where ''shipUniqueRole'' is the parameter to be passed to the :spawn macro.

====Finding the ''shipUniqueRole''====

To find the correct argument for ''shipUniqueRole'' refer to [i.e. open in a text editor]

config\shipdata.plist

Find the entry for the ship in question in the shipdata.plist. [we'll call it shipX]

<key>shipX</key>

Find the defined roles

<key>roles</key>

Use one of the defined roles as the argument for :spawn [found between ''<string></string>'']

<key>shipX</key>
<dict>
...
<key>roles</key>
<string>shipX-trader shipX-escort shipX-hunter</string>
...
</dict>

yields

:spawn shipX-trader
in the console.

====Modifying the shipdata.plist====

If all the defined roles are generic* modify the shipdata.plist from:

<key>shipX</key>
<dict>
...
<key>roles</key>
<string>trader escort hunter</string>
...
</dict>

to

<key>shipX</key>
<dict>
...
<key>roles</key>
<string>shipX-trader trader escort hunter</string>
...
</dict>

[* If the defined roles are only generic e.g trader|pirate|hunter|etc then a random ship fulfilling the role will be spawned. Not necessarily the one you wanted.]

[Make sure to use a text editor suitable for programming. One that doesn't change the encoding or add junk to the file. EOL=LF+CR]

====To park the spawned ship====

To park the spawned ship target it then enter in the console

player.ship.target.setAI("dumbAI.plist")

To manipulate sub entities (if the ship has any) use the command:

player.ship.target.subEntities[0].position = [x, y, z]

===View a rotating ship Mission Screen style===

These commands work when you are docked in the station.

[for version 1.7.3]

Enter in the console

mission.runMissionScreen(null,null,null,'shipUniqueRole')

which, using the ShipX convention yields

mission.runMissionScreen(null,null,null,'ShipX-Trader')

[Coming soon to a stable version near you...]

Enter in the console

mission.runScreen({model:'shipUniqueRole'})

which, using the ShipX convention yields

mission.runScreen({model:'ShipX-Trader'})

Viewing a Texture or Model

2009-11-21T06:28:33Z

Captain Berf:

== How to view a specific model and / or texture in Oolite. ==

===Using the in-game external views===

If the ship you want to view is your player ship simply launch the ship and press v to cycle through the external views.

===Install Debug.oxp===

1. Add Debug.oxp to your Oolite AddOns [http://wiki.alioth.net/index.php/Debug_OXP]
-- Extract the archive.
-- Move the extracted folder Debug.oxp to $PROGDIR/AddOns/
2. Install PyDebugConsole [https://developer.berlios.de/project/showfiles.php?group_id=3577]
-- Extract the archive
-- Put the directory OODebugConsole wherever you like

===Run Oolite with the DebugConsole===

1. Run the DebugConsole [WhereverIPutIt/OODebugConsole/OODebugConsole.exe]
2. Start Oolite
(If you have modified an oxp hold down the shift key during during the boot
to clear the cache)
3. Launch into space [Press 1](moving into a clear area helps).

===Spawning the ship you want to view actively in the game===

====Spawning the ship====

Type in the console

:spawn ''shipUniqueRole''

where ''shipUniqueRole'' is the parameter to be passed to the :spawn macro.

====Finding the ''shipUniqueRole''====

To find the correct argument for ''shipUniqueRole'' refer to [i.e. open in a text editor]

config\shipdata.plist

Find the entry for the ship in question in the shipdata.plist. [we'll call it shipX]

<key>shipX</key>

Find the defined roles

<key>roles</key>

Use one of the defined roles as the argument for :spawn [found between ''<string></string>'']

<key>shipX</key>
<dict>
...
<key>roles</key>
<string>shipX-trader shipX-escort shipX-hunter</string>
...
</dict>

yields

:spawn shipX-trader
in the console.

====Modifying the shipdata.plist====

If all the defined roles are generic* modify the shipdata.plist from:

<key>shipX</key>
<dict>
...
<key>roles</key>
<string>trader escort hunter</string>
...
</dict>

to

<key>shipX</key>
<dict>
...
<key>roles</key>
<string>shipX-trader trader escort hunter</string>
...
</dict>

[* If the defined roles are only generic e.g trader|pirate|hunter|etc then a random ship fulfilling the role will be spawned. Not necessarily the one you wanted.]

[Make sure to use a text editor suitable for programming. One that doesn't change the encoding or add junk to the file. EOL=LF+CR]

====To park the spawned ship====

To park the spawned ship target it then enter in the console

player.ship.target.setAI("dumbAI.plist")

To manipulate sub entities (if the ship has any) use the command:

player.ship.target.subEntities[0].position = [x, y, z]

===View a rotating ship Mission Screen style===

These commands work when you are docked in the station.

[for version 1.7.3]

Enter in the console

mission.runMissionScreen(null,null,null,'shipUniqueRole')

which, using the ShipX convention yields

mission.runMissionScreen(null,null,null,'ShipX-Trader')

[Coming soon to a stable version near you...]

Enter in the console

mission.runScreen({model:'shipUniqueRole'})

which, using the ShipX convention yields

mission.runScreen({model:'ShipX-Trader'})

Viewing a Texture or Model

2009-11-21T05:52:17Z

Captain Berf:

== How to view a specific model and / or texture in Oolite. ==

If the ship you want to view is your player ship simply launch the ship and press v to cycle through the external views.

===Install Debug.oxp===

1. Add Debug.oxp to your Oolite AddOns [http://wiki.alioth.net/index.php/Debug_OXP]
-- Extract the archive.
-- Move the extracted folder Debug.oxp to $PROGDIR/AddOns/
2. Install PyDebugConsole [https://developer.berlios.de/project/showfiles.php?group_id=3577]
-- Extract the archive
-- Put the directory OODebugConsole wherever you like

===Run Oolite with the DebugConsole===

1. Run the DebugConsole [WhereverIPutIt/OODebugConsole/OODebugConsole.exe]
2. Start Oolite
(If you have modified an oxp hold down the shift key during during the boot
to clear the cache)
3. Launch into space [Press 1](moving into a clear area helps).

===Spawning the ship you want to view actively in the game===

====Spawning the ship====

Type in the console

:spawn ''shipUniqueRole''

where ''shipUniqueRole'' is the parameter to be passed to the :spawn macro.

====Finding the ''shipUniqueRole''====

To find the correct argument for ''shipUniqueRole'' refer to [i.e. open in a text editor]

config\shipdata.plist

Find the entry for the ship in question in the shipdata.plist. [we'll call it shipX]

<key>shipX</key>

Find the defined roles

<key>roles</key>

Use one of the defined roles as the argument for :spawn [found between ''<string></string>'']

<key>shipX</key>
<dict>
...
<key>roles</key>
<string>shipX-trader shipX-escort shipX-hunter</string>
...
</dict>

yields

:spawn shipX-trader
in the console.

====Modifying the shipdata.plist====

If all the defined roles are generic* modify the shipdata.plist from:

<key>shipX</key>
<dict>
...
<key>roles</key>
<string>trader escort hunter</string>
...
</dict>

to

<key>shipX</key>
<dict>
...
<key>roles</key>
<string>shipX-trader trader escort hunter</string>
...
</dict>

[* If the defined roles are only generic e.g trader|pirate|hunter|etc then a random ship fulfilling the role will be spawned. Not necessarily the one you wanted.]

[Make sure to use a text editor suitable for programming. One that doesn't change the encoding or add junk to the file. EOL=LF+CR]

====To park the spawned ship====

To park the spawned ship target it then enter in the console

player.ship.target.setAI("dumbAI.plist")

To manipulate sub entities (if the ship has any) use the command:

player.ship.target.subEntities[0].position = [x, y, z]

===View a rotating ship Mission Screen style===

These commands work when you are docked in the station.

[for version 1.7.3]

Enter in the console

mission.runMissionScreen(null,null,null,'shipUniqueRole')

which, using the ShipX convention yields

mission.runMissionScreen(null,null,null,'ShipX-Trader')

[Coming soon to a stable version near you...]

Enter in the console

mission.runScreen({model:'shipUniqueRole'})

which, using the ShipX convention yields

mission.runScreen({model:'ShipX-Trader'})

Viewing a Texture or Model

2009-11-21T05:24:40Z

Captain Berf:

== How to view a specific model and / or texture in Oolite. ==

If the ship you want to view is your player ship simply launch the ship and press v to cycle through the external views.

===Install Debug.oxp===

1. Add Debug.oxp to your Oolite AddOns [http://wiki.alioth.net/index.php/Debug_OXP]
-- Extract the archive.
-- Move the extracted folder Debug.oxp to $PROGDIR/AddOns/
2. Install PyDebugConsole [https://developer.berlios.de/project/showfiles.php?group_id=3577]
-- Extract the archive
-- Put the directory OODebugConsole wherever you like

===Run Oolite with the DebugConsole===

1. Run the DebugConsole [WhereverIPutIt/OODebugConsole/OODebugConsole.exe]
2. Start Oolite
(If you have modified an oxp hold down the shift key during during the boot
to clear the cache)
3. Launch into space [Press 1](moving into a clear area helps).

===Spawning the ship you want to view actively in the game===

====Spawning the ship====

Type in the console

:spawn ''shipUniqueRole''

where ''shipUniqueRole'' is the parameter to be passed to the :spawn macro.

====Finding the ''shipUniqueRole''====

To find the correct argument for ''shipUniqueRole'' refer to [i.e. open in a text editor]

config\shipdata.plist

Find the entry for the ship in question in the shipdata.plist. [we'll call it shipX]

<key>shipX</key>

Find the defined roles

<key>roles</key>

Use one of the defined roles as the argument for :spawn [found between ''<string></string>'']

<key>shipX</key>
<dict>
...
<key>roles</key>
<string>shipX-trader shipX-escort shipX-hunter</string>
...
</dict>

yields

:spawn shipX-trader
in the console.

====Modifying the shipdata.plist====

If all the defined roles are generic* modify the shipdata.plist from:

<key>shipX</key>
<dict>
...
<key>roles</key>
<string>trader escort hunter</string>
...
</dict>

to

<key>shipX</key>
<dict>
...
<key>roles</key>
<string>shipX-trader trader escort hunter</string>
...
</dict>

[* If the defined roles are only generic e.g trader|pirate|hunter|etc then a random ship fulfilling the role will be spawned. Not necessarily the one you wanted.]

[Make sure to use a text editor suitable for programming. One that doesn't change the encoding or add junk to the file. EOL=LF+CR]

====To park the spawned ship====

To park the spawned ship target it then enter in the console

player.ship.target.setAI("dumbAI.plist")

To manipulate sub entities (if the ship has any) use the command:

player.ship.target.subEntities[0].position = [x, y, z]

===View a rotating ship Mission Screen style===

These commands work when you are docked in the station.

[for version 1.7.4]

Enter in the console

mission.runMissionScreen(null,null,null,'shipUniqueRole')

which, using the ShipX convention yields

mission.runMissionScreen(null,null,null,'ShipX-Trader')

[Coming soon to a stable version near you...]

Enter in the console

mission.runScreen({model:'shipUniqueRole'})

which, using the ShipX convention yields

mission.runScreen({model:'ShipX-Trader'})

Viewing a Texture or Model

2009-11-21T05:23:51Z

Captain Berf:

== How to view a specific model and / or texture in Oolite. ==

If the ship you want to view is your player ship simply launch the ship and press v to cycle through the external views.

===Install Debug.oxp===

1. Add Debug.oxp to your Oolite AddOns [http://wiki.alioth.net/index.php/Debug_OXP]
-- Extract the archive.
-- Move the extracted folder Debug.oxp to $PROGDIR/AddOns/
2. Install PyDebugConsole [https://developer.berlios.de/project/showfiles.php?group_id=3577]
-- Extract the archive
-- Put the directory OODebugConsole wherever you like

===Run Oolite with the DebugConsole===

1. Run the DebugConsole [WhereverIPutIt/OODebugConsole/OODebugConsole.exe]
2. Start Oolite
(If you have modified an oxp hold down the shift key during during the boot
to clear the cache)
3. Launch into space [Press 1](moving into a clear area helps).

===Spawning the ship you want to view actively in the game===

====Spawning the ship====

Type in the console

:spawn ''shipUniqueRole''

where ''shipUniqueRole'' is the parameter to be passed to the :spawn macro.

====Finding the ''shipUniqueRole''====

To find the correct argument for ''shipUniqueRole'' refer to [i.e. open in a text editor]

config\shipdata.plist

Find the entry for the ship in question in the shipdata.plist. [we'll call it shipX]

<key>shipX</key>

Find the defined roles

<key>roles</key>

Use one of the defined roles as the argument for :spawn [found between ''<string></string>'']

<key>shipX</key>
<dict>
...
<key>roles</key>
<string>shipX-trader shipX-escort shipX-hunter</string>
...
</dict>

yields

:spawn shipX-trader
in the console.

====Modifying the shipdata.plist====

If all the defined roles are generic* modify the shipdata.plist from:

<key>shipX</key>
<dict>
...
<key>roles</key>
<string>trader escort hunter</string>
...
</dict>

to

<key>shipX</key>
<dict>
...
<key>roles</key>
<string>shipX-trader trader escort hunter</string>
...
</dict>

[* If the defined roles are only generic e.g trader|pirate|hunter|etc then a random ship fulfilling the role will be spawned. Not necessarily the one you wanted.]

[Make sure to use a text editor suitable for programming. One that doesn't change the encoding or add junk to the file. EOL=LF+CR]

====To park the spawned ship====

To park the spawned ship target it then enter in the console

player.ship.target.setAI("dumbAI.plist")

To manipulate sub entities (if the ship has any) use the command:

player.ship.target.subEntities[0].position = [x, y, z]

===View a ship rotating Mission Screen style===

These commands work when you are docked in the station.

[for version 1.7.4]

Enter in the console

mission.runMissionScreen(null,null,null,'shipUniqueRole')

which, using the ShipX convention yields

mission.runMissionScreen(null,null,null,'ShipX-Trader')

[Coming soon to a stable version near you...]

Enter in the console

mission.runScreen({model:'shipUniqueRole'})

which, using the ShipX convention yields

mission.runScreen({model:'ShipX-Trader'})

Viewing a Texture or Model

2009-11-21T05:04:10Z

Captain Berf:

== How to view a specific model and / or texture in Oolite. ==

If the ship you want to view is your player ship simply launch the ship and press v to cycle through the external views.

===Install Debug.oxp===

1. Add Debug.oxp to your Oolite AddOns [http://wiki.alioth.net/index.php/Debug_OXP]
-- Extract the archive.
-- Move the extracted folder Debug.oxp to $PROGDIR/AddOns/
2. Install PyDebugConsole [https://developer.berlios.de/project/showfiles.php?group_id=3577]
-- Extract the archive
-- Put the directory OODebugConsole wherever you like

===Run Oolite with the DebugConsole===

1. Run the DebugConsole [WhereverIPutIt/OODebugConsole/OODebugConsole.exe]
2. Start Oolite
(If you have modified an oxp hold down the shift key during during the boot
to clear the cache)
3. Launch into space [Press 1](moving into a clear area helps).

===Spawning the ship you want to view actively in the game===

====Spawning the ship====

Type in the console

:spawn ''shipUniqueRole''

where ''shipUniqueRole'' is the parameter to be passed to the :spawn macro.

====Finding the ''shipUniqueRole''====

To find the correct argument for shipUniqueRole refer to [i.e. open in a text editor]

config\shipdata.plist

Find the entry for the ship in question in the shipdata.plist. [we'll call it shipX]

<key>shipX</key>

Find the defined roles

<key>roles</key>

Use one of the defined roles as the argument for :spawn [found between ''<string></string>'']

<key>shipX</key>
<dict>
...
<key>roles</key>
<string>shipX-trader shipX-escort shipX-hunter</string>
...
</dict>

yields

:spawn shipX-trader
in the console.

====Modifying the shipdata.plist====

If all the defined roles are generic* modify the shipdata.plist from:

<key>shipX</key>
<dict>
...
<key>roles</key>
<string>trader escort hunter</string>
...
</dict>

to

<key>shipX</key>
<dict>
...
<key>roles</key>
<string>shipX-trader trader escort hunter</string>
...
</dict>

[* If the defined roles are only generic e.g trader|pirate|hunter|etc then a random ship fulfilling the role will be spawned. Not necessarily the one you wanted.]

[Make sure to use a text editor suitable for programming. One that doesn't change the encoding or add junk to the file. EOL=LF+CR]

====To park the spawned ship====

To park the spawned ship target it then enter in the console

player.ship.target.setAI("dumbAI.plist")

To manipulate sub entities (if the ship has any) use the command:

player.ship.target.subEntities[0].position = [x, y, z]

===View a ship rotating Mission Screen style===

These commands work when you are docked in the station.

[for version 1.7.4]

Enter in the console

mission.runMissionScreen(null,null,null,'shipUniqueRole')

which, using the ShipX convention yields

mission.runMissionScreen(null,null,null,'ShipX-Trader')

[Coming soon to a stable version near you...]

Enter in the console

mission.runScreen({model:'shipUniqueRole'})

which, using the ShipX convention yields

mission.runScreen({model:'ShipX-Trader'})

Modifying a Texture

2009-11-19T00:04:38Z

Captain Berf:

=Modifying a Texture=
Textures or skins are 2D graphics that are wrapped around 3D objects by the game.

==Quick Guide==
* Find the correct texture .png found in the ''/Textures'' folder
* Back up the file you want to change
* Open the texture in a 2D graphic editing program
* Resample the image to 4096x4096
* You can hopefully see the elements that are mapped to particular features on the model
* Customize the existing image or ...
* Create a 'coloring book' outline template and replace the elements from scratch.
* Resample the image to 1024x1024.
* Save it as a .png

----

==Detailed Guide==
===Location of files===
The textures are stored as .png files in the ''/Textures'' folder. Which ''/Textures'' folder depends on whether the object is part of the standard game or part of an add-on.

$PROGDIR/
Oolite.app/
Resources/
Textures/ ''<-- Textures for standard ships live here.''
Addons/
ShipX.oxp/
Textures/ ''<-- Textures for ShipX live here.''
ShipY.oxp/
Textures/ ''<-- Textures for ShipY live here.''

===Using shipdata.plist to see which textures are loaded===
Ship textures usually carry an obvious name ''e.g.'' ShipX_body.png.
But not always. To confirm which textures are loaded for ShipX open the file shipdata.plist in a text editor.
$PROGDIR/AddOns/ShipX.oxp/Resources?/shipdata.plist

<key>ShipX</key>
<dict>
...
< >
...
</dict>

==I need a UVmap==

Modifying a Texture

2009-11-19T00:03:18Z

Captain Berf:

=Modifying a Texture=
Textures or skins are 2D graphics that are wrapped around 3D objects by the game.

==Quick Guide==
* Find the correct texture .png found in the ''/Textures'' folder
* Back up the file you want to change
* Open the texture in a 2D graphic editing program
* Resample the image to 4096x4096
* You can hopefully see the elements that are mapped to particular features on the model
* Customize the existing image or ...
* Create a 'coloring book' outline template and replace the elements from scratch.
* Resample the image to 1024x1024.
* Save it as a .png

==Detailed Guide==
===Location of files===
The textures are stored as .png files in the ''/Textures'' folder. Which ''/Textures'' folder depends on whether the object is part of the standard game or part of an add-on.

$PROGDIR/
Oolite.app/
Resources/
Textures/ ''<-- Textures for standard ships live here.''
Addons/
ShipX.oxp/
Textures/ ''<-- Textures for ShipX live here.''
ShipY.oxp/
Textures/ ''<-- Textures for ShipY live here.''

===Using shipdata.plist to see which textures are loaded===
Ship textures usually carry an obvious name ''e.g.'' ShipX_body.png.
But not always. To confirm which textures are loaded for ShipX open the file shipdata.plist in a text editor.
$PROGDIR/AddOns/ShipX.oxp/Resources?/shipdata.plist

<key>ShipX</key>
<dict>
...
< >
...
</dict>

==I need a UVmap==

Modifying a Texture

2009-11-19T00:00:35Z

Captain Berf:

=Modifying a Texture=
Textures or skins are 2D graphics that are wrapped around 3D objects by the game.

==Quick Guide==
* Find the correct texture .png found in the ''/Textures'' folder
* Back up the file you want to change
* Open the texture in a 2D graphic editing program
* Resample the image to 4096x4096
* You can hopefully see the elements that are mapped to particular features on the model
* Customize the existing image or ...
* Create a 'coloring book' outline template and replace the elements from scratch.
* Resample the image to 1024x1024.
* Save it as a .png

==Detailed Guide==
===Location of files===
The textures are stored as .png files in the ''/Textures'' folder. Which ''/Textures'' folder depends on whether the object is part of the standard game or part of an add-on.

$PROGDIR/
Oolite.app/
Resources/
Textures/ ''<-- Textures for standard ships live here.''
Addons/
ShipX.oxp/
Textures/ ''<-- Textures for ShipX live here.''
ShipY.oxp/
Textures/ ''<-- Textures for ShipY live here.''

Ship textures usually carry an obvious name ''e.g.'' ShipX_body.png.
But not always. To confirm which textures are loaded for ShipX open the file shipdata.plist in a text editor.
$PROGDIR/AddOns/ShipX.oxp/Resources?/shipdata.plist

<key>ShipX</key>
<dict>
...
< >
...
</dict>

==I need a UVmap==

Modifying a Texture

2009-11-18T23:59:54Z

Captain Berf:

=Modifying a Texture=
Textures or skins are 2D graphics that are wrapped around 3D objects by the game.

==Quick Guide==
* Find the correct texture .png found in the ''/Textures'' folder
* Back up the file you want to change
* Open the texture in a 2D graphic editing program
* Resample the image to 4096x4096
* You can hopefully see the elements that are mapped to particular features on the model
* Customize the existing image or ...
* Create a 'coloring book' outline template and replace the elements from scratch.
* Resample the image to 1024x1024.
* Save it as a .png

==Detailed Guide==
===Location of files===
The textures are stored as .png files in the ''/Textures'' folder. Which ''/Textures'' folder depends on whether the object is part of the standard game or part of an add-on.

$PROGDIR/
Oolite.app/
Resources/
Textures/ ''<-- Textures for standard ships live here.''
Addons/
ShipX.oxp/
Textures/ ''<-- Textures for ShipX live here.''
ShipY.oxp/
Textures/ ''<-- Textures for ShipY live here.''

Ship textures usually carry an obvious name ''e.g.'' ShipX_body.png.
But not always. To confirm which textures are loaded for ShipX open the file shipdata.plist in a text editor.
$PROGDIR/AddOns/ShipX/Resources?/shipdata.plist

<key>ShipX</key>
<dict>
...
< >
...
</dict>

==I need a UVmap==

Modifying a Texture

2009-11-18T23:58:37Z

Captain Berf:

=Modifying a Texture=
Textures or skins are 2D graphics that are wrapped around 3D objects by the game.

==Quick Guide==
* Find the correct texture .png found in the ''/Textures'' folder
* Back up the file you want to change
* Open the texture in a 2D graphic editing program
* Resample the image to 4096x4096
* You can hopefully see the elements that are mapped to particular features on the model
* Customize the existing image or ...
* Create a 'coloring book' outline template and replace the elements from scratch.
* Resample the image to 1024x1024.
* Save it as a .png

==Detailed Guide==
===Location of files===
The textures are stored as .png files in the ''/Textures'' folder. Which ''/Textures'' folder depends on whether the object is part of the standard game or part of an add-on.

$PROGDIR/
Oolite.app/
Resources/
Textures/ ''<-- Textures for standard ships live here.''
Addons/
ShipX/
Textures/ ''<-- Textures for ShipX live here.''
ShipY/
Textures/ ''<-- Textures for ShipY live here.''

Ship textures usually carry an obvious name ''e.g.'' ShipX_body.png.
But not always. To confirm which textures are loaded for ShipX open the file shipdata.plist in a text editor.
$PROGDIR/AddOns/ShipX/Resources?/shipdata.plist

<key>ShipX</key>
<dict>
...
< >
...
</dict>

==I need a UVmap==

Modifying a Model

2009-11-18T23:42:04Z

Captain Berf:

The underlying 3D models are contained in .dat files.

$PROGDIR/
AddOns/
ShipX/
ShipY/

To modify a .dat the file must first be converted to a Wavefront .obj file.
Conversion utilities are available here [http://svn.berlios.de/svnroot/repos/oolite-linux/trunk/tools/meshConverters/], although they are listed under Linux they are cross-platform and require the installation of Python[http://Python.org].

[Oolite forum thread about the conversion tools [http://aegidian.org/bb/viewtopic.php?t=842]]

Run dat2obj or dat2objTex on the .dat.

The resulting file can be imported into any 3D program that supports .obj.

[The free, open source program Wings3D [http://www.wings3d.com/] is the de facto standard, Blender[http://www.blender.org/] also works.]

When finished export the model as an .obj and run obj2dat.

Modifying a Model

2009-11-18T23:31:03Z

Captain Berf: Created page with 'The underlying 3D models are contained in .dat files. $PROGDIR/ AddOns/ ShipX/ ShipY/ To modify a .dat the file must first be converted to .obj. Conversi…'

The underlying 3D models are contained in .dat files.

$PROGDIR/
AddOns/
ShipX/
ShipY/

To modify a .dat the file must first be converted to .obj.
Conversion utilities are available here and require the installation of Python [http://Python.org]

Run dat2obj or dat2objTex on the .dat.

The resulting file can be imported into any 3D program that supports .obj.

[The free, open source program Wings3D [http://www.wings3d.com/] is the de facto standard]

When finished export the model as an .obj and run obj2dat.

Modifying Oolite Informal FAQ

2009-11-18T23:13:31Z

Captain Berf: /* Visual */

==I want to modify Oolite informal FAQ==

===Audio===
====I want to change the default sounds====
* [[Modifying the Audio]]

===Visual===

====I want to change the way a ship or object looks====

There are two fundamental changes that can be made: changing the skin or changing the 3D model.

* Changing the 3D model -- [[Modifying a Model]]

* Changing the skin/texture -- [[Modifying a Texture]]

===Gameplay===

Modifying the Audio

2009-11-18T23:11:05Z

Captain Berf: Created page with 'The audio for Oolite is contained in two folders: $PROGDIR/ Oolite.app/ Resources/ Music/ <-- Music lives here Sounds/ <-- Sound effect…'

The audio for Oolite is contained in two folders:

$PROGDIR/
Oolite.app/
Resources/
Music/ <-- Music lives here
Sounds/ <-- Sound effects live here

The sound files are 44 kHz, ~100-120 Kbps, Oggs.
[.ogg is an open source compression and container format. [http://www.xiph.org/]]

Audacity is the most popular free and open source audio editor. [http://audacity.sourceforge.net/]

Modifying Oolite Informal FAQ

2009-11-18T22:57:22Z

Captain Berf: /* Audio */

==I want to modify Oolite informal FAQ==

===Audio===
====I want to change the default sounds====
* [[Modifying the Audio]]

===Visual===
====I want to change the way my ship looks====
====I want to change the way a ship or object looks====

There are two fundamental changes that can be made: changing the skin or changing the 3D model.

* Changing the 3D model

* Changing the skin/texture -- [[Modifying a Texture]]

===Gameplay===

Modifying a Texture

2009-11-18T05:08:27Z

Captain Berf:

Textures or skins are 2D graphics that are wrapped around 3D objects by the game.

==Quick Guide==
* Find the correct texture .png found in the ''/Textures'' folder
* Back up the file you want to change
* Open the texture in a 2D graphic editing program
* Resample the image to 4096x4096
* You can hopefully see the elements that are mapped to particular features on the model
* Customize the existing image or ...
* Create a 'coloring book' outline template and replace the elements from scratch.
* Resample the image to 1024x1024.
* Save it as a .png

==Detailed Guide==
===Location of files===
The textures are stored as .png files in the ''/Textures'' folder. Which ''/Textures'' folder depends on whether the object is part of the standard game or part of an add-on.

$PROGDIR/
Oolite.app/
Resources/
Textures/ ''<-- Textures for standard ships live here.''
Addons/
ShipX/
Textures/ ''<-- Textures for ShipX live here.''
ShipY/
Textures/ ''<-- Textures for ShipY live here.''

Ship textures usually carry an obvious name ''e.g.'' ShipX_body.png.
But not always. To confirm which textures are loaded for ShipX open the file shipdata.plist in a text editor.
$PROGDIR/AddOns/ShipX/Resources?/shipdata.plist

<key>ShipX</key>
<dict>
...
< >
...
</dict>

Modifying a Texture

2009-11-18T04:57:59Z

Captain Berf: /* Location of files */

Textures or skins are 2D graphics that are wrapped around 3D objects by the game.

=Quick Guide=
* Find the correct texture .png found in the ''/Textures'' folder
* Back up the file you want to change
* Open the texture in a 2D graphic editing program
* Resample the image to 4096x4096
* You can hopefully see the elements that are mapped to particular features on the model
* Customize the existing image or ...
* Create a 'coloring book' outline template and replace the elements from scratch.
* Resample the image to 1024x1024.
* Save it as a .png

=Detailed Guide=
==Location of files==
The textures are stored as .png files in the ''/Textures'' folder. Which ''/Textures'' folder depends on whether the object is part of the standard game or part of an add-on.

$PROGDIR/
Oolite.app/
Resources/
Textures/ ''<-- Textures for standard ships live here.''
Addons/
ShipX/
Textures/ ''<-- Textures for ShipX live here.''
ShipY/
Textures/ ''<-- Textures for ShipY live here.''

Ship textures usually carry an obvious name ''e.g.'' ShipX_body.png.
But not always. To confirm which textures are loaded for ShipX open the file shipdata.plist in a text editor.
$PROGDIR/AddOns/ShipX/Resources?/shipdata.plist

<key>ShipX</key>
<dict>
...
< >
...
</dict>

Modifying a Texture

2009-11-18T04:56:41Z

Captain Berf: /* Quick Guide */

Textures or skins are 2D graphics that are wrapped around 3D objects by the game.

=Quick Guide=
* Find the correct texture .png found in the ''/Textures'' folder
* Back up the file you want to change
* Open the texture in a 2D graphic editing program
* Resample the image to 4096x4096
* You can hopefully see the elements that are mapped to particular features on the model
* Customize the existing image or ...
* Create a 'coloring book' outline template and replace the elements from scratch.
* Resample the image to 1024x1024.
* Save it as a .png

=Detailed Guide=
==Location of files==
The textures are stored as .png files in the ''/Textures'' folder. Which ''/Textures'' folder depends on whether the object is part of the standard game or part of an add-on.

$PROGDIR/
Oolite.app/
Resources/
Textures/ ''<-- Textures for standard ships live here.''
Addons/
ShipX/
Textures/ ''<-- Textures for ShipX live here.''
ShipY/
Textures/ ''<-- Textures for ShipY live here.''

Ship textures usually carry an obvious name ''e.g.'' ShipX_body.png.
But not always. To confirm which textures are loaded for ShipX open the file shipdata.plist in a text editor.
$PROGDIR/AddOns/ShipX/shipdata.plist

<key>ShipX</key>
<dict>
...
< >
...
</dict>

Modifying a Texture

2009-11-18T04:55:56Z

Captain Berf:

Textures or skins are 2D graphics that are wrapped around 3D objects by the game.

=Quick Guide=
* Find the correct texture .png found in the ''/Textures'' folder
* Back up the file you want to change
* Open the texture in a 2D graphic editing program
* Resample the image to 4096x4096
* You can hopefully see the elements that are mapped to particular features on the model
* Customize the existing image or ...
* Create a 'coloring book' outline and replace the elements from scratch.
* Resample the image to 1024x1024.
* Save it as a .png

=Detailed Guide=
==Location of files==
The textures are stored as .png files in the ''/Textures'' folder. Which ''/Textures'' folder depends on whether the object is part of the standard game or part of an add-on.

$PROGDIR/
Oolite.app/
Resources/
Textures/ ''<-- Textures for standard ships live here.''
Addons/
ShipX/
Textures/ ''<-- Textures for ShipX live here.''
ShipY/
Textures/ ''<-- Textures for ShipY live here.''

Ship textures usually carry an obvious name ''e.g.'' ShipX_body.png.
But not always. To confirm which textures are loaded for ShipX open the file shipdata.plist in a text editor.
$PROGDIR/AddOns/ShipX/shipdata.plist

<key>ShipX</key>
<dict>
...
< >
...
</dict>

Modifying a Texture

2009-11-18T04:41:35Z

Captain Berf: /* Location of files */

Textures or skins are 2D graphics that are wrapped around 3D objects by the game.

==Location of files==
The textures are stored as .png files in the ''/Textures'' folder. Which ''/Textures'' folder depends on whether the object is part of the standard game or part of an add-on.

$PROGDIR/
Oolite.app/
Resources/
Textures/ ''<-- Textures for standard ships live here.''
Addons/
ShipX/
Textures/ ''<-- Textures for ShipX live here.''
ShipY/
Textures/ ''<-- Textures for ShipY live here.''

Ship textures usually carry an obvious name ''e.g.'' ShipX_body.png.
But not always. To confirm which textures are loaded for ShipX open the file shipdata.plist in a text editor.
$PROGDIR/AddOns/ShipX/shipdata.plist

<key>ShipX</key>
<dict>
...
< >
...
</dict>

Modifying a Texture

2009-11-18T04:38:16Z

Captain Berf: /* Modifying a Texture */

Modifying a Texture

2009-11-18T04:23:40Z

Captain Berf: Created page with '=Modifying a Texture= Textures or skins are 2D graphics that are wrapped around 3D objects by the game. ==Location== The textures are stored as .png files in the ''/Textures'' …'

=Modifying a Texture=

Textures or skins are 2D graphics that are wrapped around 3D objects by the game.

==Location==
The textures are stored as .png files in the ''/Textures'' folder. Which ''/Textures'' folder depends on whether the object is part of the standard game or part of an add-on.

$PROGDIR/
Oolite.app/
Resources/
Textures/ ''<-- Textures for standard ships live here.''
Addons/
ShipX/
Textures/ ''<-- Textures for ShipX live here.''
ShipY/
Textures/ ''<-- Textures for ShipY live here.''

Modifying Oolite Informal FAQ

2009-11-18T04:06:55Z

Captain Berf: /* I want to change the way a ship or object looks */

==I want to modify Oolite informal FAQ==

===Audio===
====I want to change the default sounds====

===Visual===
====I want to change the way my ship looks====
====I want to change the way a ship or object looks====

There are two fundamental changes that can be made: changing the skin or changing the 3D model.

* Changing the 3D model

* Changing the skin/texture -- [[Modifying a Texture]]

===Gameplay===

Modifying Oolite Informal FAQ

2009-11-18T03:56:48Z

Captain Berf: Created page with '==I want to modify Oolite informal FAQ== ===Audio=== ====I want to change the default sounds==== ===Visual=== ====I want to change the way my ship looks==== ====I want to chang…'

OXP howto

2009-11-18T03:45:52Z

Captain Berf: /* Textures */

[[Image:oolite-oxp-icon.png|100px|right|OXP icon]]
An '''Oolite Expansion Pack''' can cause many big changes or additions to Oolite's gameplay, or it may represent just a small, subtle alteration. By appearances, there is no way to tell what is inside, as it's merely a folder with the added extention '''.oxp'''. Inside, it will at least contain a folder named ''Config'', and possibly other folders such as ''AIs'', ''Models'', ''Textures'', ''Sounds'', etc. It is down to the goal of the OXP, which ways to combine elements to the OXP's contents.

=== AIs ===

The folder named AIs contains any AI.plist additions the OXP might use.

* [[OXP howto AI|Making Oolite AI]]

=== Config===

This folder contains [[Property lists]] such as:

* ''[[shipdata.plist]]'' that introduces any new entity (ships, stations, objects etc.) to Oolite.
* ''[[shipdata-overrides.plist]]'' that selectively can replace shipentries in other shipdata.plists
* ''[[shipyard.plist]]'' that introduces new ships available for player purchase.
* ''[[shipyard-overrides.plist]]'' that selectively can replace shipentries in other shipyard.plists
* ''[[script.plist]]'' to handle conditional ''script actions''. Note that [[script.js]] will be loaded in preference to script.plist if both exist. ([[script.oos]] was briefly introduced during 1.70 development but is now depracated in favour of JS.)
* ''[[planetinfo.plist]]'' that plots system specific changes from the default. May also contain ''script actions''.
* ''[[commodities.plist]]'' that contains information for each commodity in a market.
* ''[[misc plists|demoships.plist]]'' that selects demoships to show on startup.
* ''[[misc plists|descriptions.plist]]'' that adds vocabulary to Oolite texts.
* ''[[hud.plist]]'' that allows for changes or a radically new ''Head-Up Display''.
* ''[[characters.plist]]'' that adds non-player characters to Oolite.
* ''[[equipment.plist]]'' lists upgrades available from the Shipyard.
* ''[[misc plists|pirate-victim-roles.plist]]'' that defines which roles should act as traders.
* ''[[missiontext.plist]]'', ''[[speech_pronunciation_guide.plist]]'' are some of the other custom methods.

All plist files except for those introducing new AI, belong in Config.

In its simplest form, an OXP could contain only a Config with an altering ''script.plist'' or ''planetinfo.plist''. An OXP that adds a new ship needs a ''shipdata.plist'' entry, and unless it is based entirely on existing Oolite data, would include a model and texture.

* [[OXP howto plist|Making Oolite plists]]

=== Models===

Oolite models need to be in the '''.dat''' format. There are utilities available that convert models made in Wings 3D (.obj) and Meshwork (.mesh) into this. A .dat file can be opened in a plain text editor to view the object's assigned texture names and see that they correspond with the actual file names in the Textures folder. The .dat file must be named exactly as it is referenced in the shipdata ''model'' entry.

* [[OXP howto model|Making Oolite models]]

=== Textures===

Oolite's textures are in the '''.png''' format, usually at a standard 1024x1024 size, and must be named exactly as they are named in the .dat file.

* [[OXP howto texture|Making Oolite textures]]

Viewing a specific texture and / or model in Oolite.
"I made one. How do I proof it?"

* [[Viewing a Texture or Model]]

=== Requires ===

Every oxp should contain a [[Property lists]] with the name ''requires.plist'' that is placed at the main level of the oxp folder. It contains just a dictionary with two entries: ''version'' and ''max_version''. ''version'' is the lowest Oolite version the code can run on. This ensures that older Oolite versions don't behave bad or crash because they load an oxp that does contain unknown stuff. The max_version is only needed when you want an oxp to not run with newer Oolite versions. Very useful for adding in test versions of an oxp to ensure this test version is not used forever.

=== A preview of things to come ===

The scripting environment is being reworked to use JavaScript as the core scripting language. See [[Scripting Oolite with JavaScript]] for more information.

== External links ==

*[http://oolite.aegidian.org/cyoship/ Oolite Tutorial-Meshwork Shipbuilding]
*[http://oolite.aegidian.org/cyoship2/ Oolite Tutorial-Wings 3D Shipbuilding]

[[Category:Oolite]]
[[Category:Oolite scripting]]

OXP howto

2009-11-18T03:35:09Z

Captain Berf: /* Textures */

[[Image:oolite-oxp-icon.png|100px|right|OXP icon]]
An '''Oolite Expansion Pack''' can cause many big changes or additions to Oolite's gameplay, or it may represent just a small, subtle alteration. By appearances, there is no way to tell what is inside, as it's merely a folder with the added extention '''.oxp'''. Inside, it will at least contain a folder named ''Config'', and possibly other folders such as ''AIs'', ''Models'', ''Textures'', ''Sounds'', etc. It is down to the goal of the OXP, which ways to combine elements to the OXP's contents.

=== AIs ===

The folder named AIs contains any AI.plist additions the OXP might use.

* [[OXP howto AI|Making Oolite AI]]

=== Config===

This folder contains [[Property lists]] such as:

* ''[[shipdata.plist]]'' that introduces any new entity (ships, stations, objects etc.) to Oolite.
* ''[[shipdata-overrides.plist]]'' that selectively can replace shipentries in other shipdata.plists
* ''[[shipyard.plist]]'' that introduces new ships available for player purchase.
* ''[[shipyard-overrides.plist]]'' that selectively can replace shipentries in other shipyard.plists
* ''[[script.plist]]'' to handle conditional ''script actions''. Note that [[script.js]] will be loaded in preference to script.plist if both exist. ([[script.oos]] was briefly introduced during 1.70 development but is now depracated in favour of JS.)
* ''[[planetinfo.plist]]'' that plots system specific changes from the default. May also contain ''script actions''.
* ''[[commodities.plist]]'' that contains information for each commodity in a market.
* ''[[misc plists|demoships.plist]]'' that selects demoships to show on startup.
* ''[[misc plists|descriptions.plist]]'' that adds vocabulary to Oolite texts.
* ''[[hud.plist]]'' that allows for changes or a radically new ''Head-Up Display''.
* ''[[characters.plist]]'' that adds non-player characters to Oolite.
* ''[[equipment.plist]]'' lists upgrades available from the Shipyard.
* ''[[misc plists|pirate-victim-roles.plist]]'' that defines which roles should act as traders.
* ''[[missiontext.plist]]'', ''[[speech_pronunciation_guide.plist]]'' are some of the other custom methods.

All plist files except for those introducing new AI, belong in Config.

In its simplest form, an OXP could contain only a Config with an altering ''script.plist'' or ''planetinfo.plist''. An OXP that adds a new ship needs a ''shipdata.plist'' entry, and unless it is based entirely on existing Oolite data, would include a model and texture.

* [[OXP howto plist|Making Oolite plists]]

=== Models===

Oolite models need to be in the '''.dat''' format. There are utilities available that convert models made in Wings 3D (.obj) and Meshwork (.mesh) into this. A .dat file can be opened in a plain text editor to view the object's assigned texture names and see that they correspond with the actual file names in the Textures folder. The .dat file must be named exactly as it is referenced in the shipdata ''model'' entry.

* [[OXP howto model|Making Oolite models]]

=== Textures===

Oolite's textures are in the '''.png''' format, usually at a standard 1024x1024 size, and must be named exactly as they are named in the .dat file.

* [[OXP howto texture|Making Oolite textures]]

=== Requires ===

Every oxp should contain a [[Property lists]] with the name ''requires.plist'' that is placed at the main level of the oxp folder. It contains just a dictionary with two entries: ''version'' and ''max_version''. ''version'' is the lowest Oolite version the code can run on. This ensures that older Oolite versions don't behave bad or crash because they load an oxp that does contain unknown stuff. The max_version is only needed when you want an oxp to not run with newer Oolite versions. Very useful for adding in test versions of an oxp to ensure this test version is not used forever.

=== A preview of things to come ===

The scripting environment is being reworked to use JavaScript as the core scripting language. See [[Scripting Oolite with JavaScript]] for more information.

== External links ==

*[http://oolite.aegidian.org/cyoship/ Oolite Tutorial-Meshwork Shipbuilding]
*[http://oolite.aegidian.org/cyoship2/ Oolite Tutorial-Wings 3D Shipbuilding]

[[Category:Oolite]]
[[Category:Oolite scripting]]

Viewing a Texture or Model

2009-11-18T03:30:04Z

Captain Berf: /* How to view a specific model and / or texture in Oolite. */

== How to view a specific model and / or texture in Oolite. ==

If the ship you want to view is your player ship simply launch the ship and press v to cycle through the external views.

Otherwise ...

===Install Debug.oxp===

1. Add Debug.oxp to your Oolite AddOns [http://wiki.alioth.net/index.php/Debug_OXP]
-- Extract the archive.
-- Move the extracted folder Debug.oxp to $PROGDIR/AddOns/
2. Install PyDebugConsole [https://developer.berlios.de/project/showfiles.php?group_id=3577]
-- Extract the archive
-- Put the directory OODebugConsole wherever you like

===Run Oolite with the DebugConsole===

1. Run the DebugConsole [WhereverIPutIt/OODebugConsole/OODebugConsole.exe]
2. Start Oolite (If you have modified an oxp hold down the shift key during during the boot
(holding down shift clears the cache))
3. Launch into space [Press 1](moving into a clear area helps).

===Spawning the ship you want to view===

Type in the console

:spawn ''role''

where ''role'' is the parameter to be passed to the :spawn macro.

To find the correct argument for role refer to [i.e. open in a text editor]

config\shipdata.plist

Find the entry for the ship in question in the shipdata.plist. [we'll call it shipX]

<key>shipX</key>

Find the defined roles

<key>roles</key>

Use one of the defined roles as the argument for :spawn [found between ''<string></string>'']

<key>shipX</key>
<dict>
...
<key>roles</key>
<string>shipX-trader shipX-escort shipX-hunter</string>
...
</dict>

yields

:spawn shipX-trader
in the console.

====Modifying the shipdata.plist====

If all the defined roles are generic* modify the shipdata.plist from:

<key>shipX</key>
<dict>
...
<key>roles</key>
<string>trader escort hunter</string>
...
</dict>

to

<key>shipX</key>
<dict>
...
<key>roles</key>
<string>shipX-trader trader escort hunter</string>
...
</dict>

[* If the defined roles are only generic e.g trader|pirate|hunter|etc then a random ship fulfilling the role will be spawned. Not necessarily the one you wanted.]

[Make sure to use a text editor suitable for programming. One that doesn't change the encoding or add junk to the file. EOL=LF+CR]

===To park the spawned ship===

To park the spawned ship target it then enter in the console

player.ship.target.setAI("dumbAI.plist")

To manipulate sub entities (if the ship has any) use the command:

player.ship.target.subEntities[0].position = [x, y, z]

Viewing a Texture or Model

2009-11-18T03:06:13Z

Captain Berf: How to view a specific model and / or texture in Oolite

== How to view a specific model and / or texture in Oolite. ==

If the ship you want to view is your player ship simply launch the ship and press v to cycle through the external views. Otherwise ...

Install Debug.oxp

Installing Debug.oxp

1. Add Debug.oxp to your Oolite Addons [http://wiki.alioth.net/index.php/Debug_OXP]
2. Install PyDebugConsole [https://developer.berlios.de/project/showfiles.php?group_id=3577]

Run Oolite with the DebugConsole

1. Run the DebugConsole
2. Start Oolite (holding down the shift key while it boots if an oxp has been changed
(holding down shift clears the cache))
3. Launch into space (moving into a clear area helps).

Spawning the ship you want to view

Type in the console
:spawn ''role''
where ''role'' is the parameter to be passed to the :spawn macro.

To find the correct argument for role refer to [i.e. open in a text editor]
config\shipdata.plist

Find the entry for the ship in question in the shipdata.plist. [we'll call it shipX]

<key>shipX</key>
Find the defined roles
<key>roles</key>
Use one of the defined roles as the argument for :spawn [found between <string></string>]
<key>shipX</key>
<dict>
...
<key>roles</key>
<string>shipX-trader shipX-escort shipX-hunter</string>
...
</dict>
yields
:spawn shipX-trader
in the console.

If all the defined roles are generic* modify the shipdata.plist from:
<key>shipX</key>
<dict>
...
<key>roles</key>
<string>trader escort hunter</string>
...
</dict>

to

<key>shipX</key>
<dict>
...
<key>roles</key>
<string>shipX-trader trader escort hunter</string>
...
</dict>

[* If the defined roles are only generic e.g trader|pirate|hunter|etc then a random ship fulfilling the role will be spawned. Not necessarily the one you wanted.]

[Make sure to use a text editor suitable for programming. One that doesn't change the encoding or add junk to the file. EOL=LF+CR]

To park the spawned ship target it then enter in the console:
player.ship.target.setAI("dumbAI.plist")

To manipulate sub entities (if the ship has any) use the command: Code:
player.ship.target.subEntities[0].position = [x, y, z]

Debug OXP

2009-11-15T21:58:34Z

Captain Berf: /* External JavaScript console support */

'''Debug.oxp''' is a special OXP that enables JavaScript console support in test releases of Oolite (1.70 and later). It also adds a menu with various debug facilities under Mac OS X.

=== Downloads ===
[[Media:DebugOXP-173.zip|Debug OXP for Oolite 1.73]] (162 KiB)<br>
[[Media:DebugOXP-172.zip|Debug OXP for Oolite 1.72]] (161 KiB)<br>
[[Media:DebugOXP-171.zip|Debug OXP for Oolite 1.71]] (149 KiB)<br>
[[Media:DebugOXP-170.zip|Debug OXP for Oolite 1.70]] (117 KiB)

== External JavaScript console support ==
On all platforms, installing Debug.oxp enables support for external console applications using the [[Oolite debug console TCP protocol]]. By default, it will attempt to connect to a console running on the same computer, but this can be changed by specifying a different <code>console-host</code> (and, optionally, <code>console-port</code>) in ''debugConfig.plist''. For external console support on the same computer under Mac OS X, <code>console-host</code> must be explicitly set to “127.0.0.1”; if this is not done, the [[#Integrated JavaScript console|integrated JavaScript console]] will be used instead. For information on using a console (integrated or external), see [[#Using the JavaScript console|Using the JavaScript console]] below.

On Debian or Ubuntu Linux you will need (at least) the packages <code>blt python-tk tk8.5</code> (or the equivalents in other distros.)

== Mac OS X-specific features ==
Under Mac OS X, the Debug OXP provides a menu with various debugging options and an integrated JavaScript console, as well as enabling external console support as on all platforms.

=== Debug menu ===
[[Image:Oolite-debug-menu.png|494px]]

The Debug menu provides options to
* Show the Oolite run log in the standard Console application.
* Enable or disable various classes of log message at runtime (like editing ''logcontrol.plist'', without the need to restart Oolite).
* Enable various testing features, such as drawing of bounding boxes.
* Show the JavaScript console, and specify when it should be shown automatically. (This may not have any effect with external consoles, depending on the external console implementation.)
* Create a ship of any role near the main station (equivalent to the <code>:spawn</code> [[#Macros|macro]]).
Note: some of these features are implemented by sending JavaScript messages to the [[#The console script|console script]]. If the script has been modified, some features may not work properly.

The Log Message Classes submenu can be modified by editing ''debugLogMessageClassesMenu.plist'', found inside the OXP. This is merged from Config directories in the usual fashion.

=== Integrated JavaScript console ===
[[Image:Oolite debug protocol example 1.png|594px]]

The integrated JavaScript console provides a window within Oolite which acts as a [[#Using the JavaScript console|JavaScript console]]. It can be shown using the Show JavaScript Console command in the Debug menu, unless external console mode has been enabled by setting <code>console-host</code> in ''debugConfig.plist''.

The integrated console has a 100-line memory. To see previous commands, press ⇞ (Page Up) or ⌥↑ (Option-Up Arrow). You can go the other way in the obvious manner.

== Using the JavaScript console ==
The JavaScript console, whether integrated or external, provides a powerful mechanism for interactively manipulating the game world. It can be used to issue simple commands, like <code>player.awardEquipment("EQ_FUEL_INJECTION")</code>. It can be used to inspect properties of entities in the game world. And it can be used to develop scripts, by rewriting and testing methods of live ship scripts and world scripts.

=== Macros ===
Macros are a special type of command prefixed with a colon. Instead of being interpreted as a JavaScript command, a macro is looked up in a dictionary, and the result is used as the “real” command. For instance, if you enter the command <code>:listM</code> (short for “list macros”), the macro dictionary is queried for the string “listM”, and (by default) the code <code>for (let prop in macros) { ConsoleMessage('macro-list', ':' + prop) }</code> is found and executed. This code is called the ''expansion'' of the macro. The result is a list of macros being printed:
:clr
:clear
:spawn
:bgColor
:showM
:rmFgColor
::
:d
:ds
:listM
:setM
:delM
:fgColor
:rmBgColor
:resetM

As you can see in the example, To see the expansion of a macro without executing it, use <code>:showM</code>:
> :showM :delM
:delM = deleteMacro(PARAM)

When a macro with the word <code>PARAM</code> is executed, <code>PARAM</code> is replaced with any text following the macro name, surrounded in quotation marks. This is how <code>:showM</code> functions, for example; the string “:showM :delM” is expanded to “showMacro(":delM")”, causing the JavaScript function <code>showMacro()</code>, which is part of the [[#The console script|console script]], to be called. You can see the implementation of <code>showMacro()</code> by entering <code>showMacro</code> – without any parentheses – into the console.

An initial set of macros is loaded from ''debugConfig.plist''. If you edit any macros, using <code>:setM</code> or <code>:delM</code>, all macros are saved in Oolite’s preferences from that point forwards. This means that you don’t have to re-enter any macros you write with <code>:setM</code> after restarting Oolite.

The following example creates a simple :msg macro:
> :setM msg ConsoleMessage(' ',PARAM)
If you then type:
> :msg Hello World
The macro will be expanded, and you'll see “Hello World” on the console. However, macros are not functions, so you cannot use macros in the middle of javascript, or as part of another macro.

=== The console script ===
While an external or integrated console is required to provide a means of user interaction, most of the actual behaviour of the console is implemented in JavaScript, in a script called ''oolite-mac-js-console.js''. (This is a mistake; the name will be changed to ''oolite-debug-console.js'' in Oolite 1.71.) Input typed into the console is passed to the console script, which then generates output. The console script is also informed of log messages and JavaScript errors, and provides a global function, <code>ConsoleMessage(colorCode: String, message: String)</code>, to write messages to the console using its background colour support. Lastly, the console script implements the entire macro system.

This means that the console’s behaviour can be extensively customized, for instance, by replacing the macro system with something more powerful. There are two basic approaches to doing this:
* Creating a custom script (or a copy) with the same name, in an OXP which loads later than Debug.oxp (e.g., one which has a name which comes later in alphabetical order).
* Using a normal world script, and changing the console script object at startup.
The latter approach has the advantage that it can continue to work with future versions of the console script, and multiple patches can coexist. For example, a modification to supplement the macro system with a better one might look as follows:
this.name = "my-super-console-macros"

this.startUp = function()
{
// Ensure debug console is installed
if (!debugConsole) return

// Save original implementation of consolePerformJSCommand
// Note the prefix, used to ensure uniqueness. If several scripts patch
// the same method, it's important that they use different names.
debugConsole.mySuperConsoleMacros_original_consolePerformJSCommand = debugConsole.consolePerformJSCommand

// Replace debugConsole.consolePerformJSCommand with custom function
debugConsole.consolePerformJSCommand = function(command)
{
// Note that in this function "this" will refer to debugconsole, not
// my-super-console-macros, since the function will be called as a
// method of debugConsole.

// Strip leading spaces, same code as original function.
while (command.charAt(0) == " ")
{
command = command.substring(1)
}

if (command.charAt(0) == "!")
{
// Super macro call detected.
// Insert super macro system here.
}
else
{
// Otherwise, call through to original method.
debugConsole.mySuperConsoleMacros_original_consolePerformJSCommand(command)
}
}
}
This same patching technique, incidentally, can be used to modify scripts at runtime, either from the console or from other scripts.

{{unclassified-OXP}}
[[Category:Oolite utilities]]