OXP howto model

Maaarcooose's finished model of the Odyssey, prior to texturing

Textured Odyssey

Introduction

Oolite draws its ships from models in the .dat format, but this is an Oolite-only format. The models made in modelling programs are most commonly in .obj files. Therefore, to see a home-made model appear in the game, one needs to convert the .obj file to a .dat, which can usually be done successfully with a python script (Obj2DatTex.py : see below).

Therefore, to tweak someone else's game model, one takes the .dat from an OXP, and converts it back to an .obj with a different python script (Dat2ObjTex.py). This is not as reliable, Murgh currently has a 60-70% success rate. Usually old models are no problem, but newer models often don't work. For instance, he's failed to convert the modern buoy. But has succeeded with all of his old models, and almost all of Aegidian's old models.

But some of the old Aegidians can come with a twist. When you open them, the texture can be mirror-backwards, or even weirder, project itself from the inside out. Like taking a picture and stuffing it inside a goldfishbowl, you see it, but it's very wrong when you expect it to be on the outside. It turned out to be fixable in Wings. Source (2022)

Which programme?

Wings3D was probably the most popular programme for creating the early models. In recent years Gsagostinho moved to it from Blender in 2017. On the other hand, Killer Wolf moved in the opposite direction.

If you have a windows computer, the old Truespace 4.3 is supposed to be very easy to learn to use. See discussion here and download here.

Create your model

in Wings3D or a similar program.

• For Blender specifically see Blender 3d Modeling Tutorials (2011) - and see also cgcookie.com, and JackieBean on the joys of Blender (2017).

How you do this is up to your creativity, but Aegidian has created the following tutorial for Wings3D.

	Launch Wings3D and select the object mode.
	Right-click in the workspace to pop up the object menu. Select the options for the cube.
	Cubes created by Wings3D measure one unit on a side. In Oolite these units are meters and a 1m x 1m x 1m spaceship is a bit small, so we're going to scale it to 30m wide, 10m tall, and 30m long. You'll need to dolly the camera away from your object a bit to be able to see it all in the view now. I use the scroll-wheel to do this, but ctrl-alt-[left mouse button] and up or down will also work. Another approach is to create the standard sized cube and Right-click and choose .Scale Axis. Choose the .X. axis then press tab to allow numeric input, this is a percentage, so enter 3000 to scale the objects x-axis dimension to 30m. Do the same scaling on the .Y axis, scaling by 1000%. and on the .Z. axis scaling by 3000%.
	This gives us our basic shape, 30m wide by 30m long by 10m high. Now some details, we'll add a bevel for the front viewscreen and some fins.
	First the bevel, select the edges mode and press space to clear the current selection.
	Select the upper front edge, Right-click to pop up the menu and choose Bevel. Move the mouse until you've got the right look, then left-click to set the bevel. You can also press tab to allow numeric entry of the bevel amount again.
	Voila. The first step is done. Next the fins. These will be a bit trickier.
	Select edges mode again and press space to clear the selection. Then choose one of the two upper edges going from front to back.
	Right-click for the menu and then choose .Cut and choose 2 2 to cut the line into two pieces. Do the same for the line on the other side. You'll find yourself in points mode, with the indicated point selected.
	Now we need a quick trick to make life easier - choose faces mode and press command-a to select all faces.
	Right-click and choose Tesselate and then Triangulate, which will make turn all the flat faces into bunches of triangles.
	Return to edges modes and select the two edges to become fins.
	Right-click and choose .Extrude and Normal and move the mouse until you are pleased.
	Tadaa! A flying brick.

pic 1

pic 2

pic 3

pic 4

pic 5

pic 6

pic 7

If you've read the tutorial above it's time to think about a few more things.

Optimize

Optimizing models and textures for a game is no fun, specially if it's a model with lots of greebles and funny details.

Simple example

So let's stick with a simple example - a simple cone combined with a cube. When creating the UV-Map in Wings3D this map is really in no way optimized. Doing optimizations as postprocess is a real pain, believe me .-)

Let's say you have created a model in Wings3D (pic 1) and created the UV-Map (pic 2). You can see that Wings3D does some preparations for you, e.g. the UV information is taking place in the maps area and the polygons are separated (in chunks), based on the method you've used to create the UV-Map. It's a good starting point but far away from a optimum for a game.

Wasted texture informations

You can see in a few OXPs background images in the UV-Maps (pic 3). This is just wasted texture information, results in bigger filesizes and and makes optimization tools pretty senseless. These tools are using Deflate, LZ77, RLE (Run-length_encoding) and other algorithms to optimize the texture information streams in the maps. Better use a solid color (black, grey or white).

Wasted faces

Wings3D is a box-modeller and creating objects in Wings3D always results in closed objects. Result is that quite a few faces are just wasted (pic 4), because they are not visible at all, but still eating memory and processing time. This can easily go in a few thousands of faces when a lot of models are used in installed OXPs. Luckily there's a way as Wings3D provides a hole material. This is a special feature to reduce the amount of data when exporting the model as .obj as the faces won't appear in the exported model and UV-Map.

Resort the map

The next step is to resort (and sometimes scale) the polys in the UV-Mapper. Best practice is to leave a little bit space between polys (pic 5). This is a lesson I had to learn with my models. I was always wondering why some artifacts appeard at the edges and why the mipmapping doesn't work properly.

Mipmapping

To get it working properly expand the areas with real texture information by a few pixels (pic 6). Oolite will do the mipmapping (if its available) automagically. Mipmapping or Level of Detail (LOD) is a antialiasing technique to improve the quality when textures are minified / magnified. See Mipmap for more infos.

Tesselation is evil

And last but not least tesselation (or subdivision) is evil if its used to smooth objects appearance. We can see it in a growing number of released OXPs, and it is really the worst case. Tesselation (pic 7) is a time eater for a game as it increases vertex and face counts a lot and often enough results in higher texture sizes. Both are adding time to the setup of entities whenever they are spawned in the game. Oolite handles smooth groups and hard/soft edges so in most cases there is absolutely no need to raise v/f counts. A really simple example how to use the smoothing option in combination with materials entries in Oolite can be found in the RVandGS.oxp.

Details and Greebles

Another point to consider is if a detail has to be done in the model itself or if this can be placed in a normal map.

Export the model

to obj( mtl texture) and convert to *.dat format.

The picture above shows 3 simple steps to export the model and use one of the converter scripts to get the .dat file.

• If you have the Wings stuff ready for export (means a model with UV-Map), simply use the Wavefront (obj) exporter (Step 1+2). You'll need to configure it as shown in Step 2. Once exported you have three files (.obj, .mtl and .png).
• Copy the Obj2DatTexNorm.py from Github to your folder where the model has been saved to.
• Open a shell and switch to the folder with the model (and script) and type in: Obj2DatTexNorm.py mymodel.obj (Step 3).

Python 2.5

Obj2DatTex.py still needs this version.

Python 2.7

Please note that the converter script Obj2DatTexNorm.py needs Python 2.7 or higher (but doesn't work out of the box with 3.x!!). There is still Obj2DatTex.py available which will work with Python 2.5, but the recommended tool is Obj2DatTexNorm.py.

Python 3

There is a branch python3 that should contain the necessary changes.

Add model to OXP

Supply the in-game values relevant to your model into shipdata.plist.

TODO: What values from the shipdata.plist reference are really required? What are recommended minimum values?

TODO: What needs to be done to make a ship/station/... appear in the game?

TODO: What needs to be done to make a ship player-flyable?

Here are some good instructions to get started: https://bb.oolite.space/viewtopic.php?p=205930#p205930 Essentially, they are:

- locate the AddOns directory,

- make a subdir named YourShip_0.1.oxp,

- step into and make at least these subdirs: Config, Models and Textures,

- copy a working [wiki]shipdata.plist[/wiki] and [wiki]shipyard.plist[/wiki] file into the Config folder from any playable ship OXP,

- change at least the dataKey of the ship which is usually "shipname-player" in these files to "yourshipname-player".

You can use the original model and textures: copy the contents of this directories also, or you can build your own model into the Models/yourship.dat file: [wiki]OXP_howto_model[/wiki].

If you want to start the game in your ship then install [wiki]Start_Choices[/wiki] OXP and replace the dataKey of a ship, for example the "cobramk1-player" to "yourshipname-player" in AddOns/start_choices_1.4.oxp/Config/script.js (105. line) .

Then start the game with holding down the Shift key and choose the replaced ship.

Example

Possibly the simplest OXP ship is the Strut - part of the older versions of the Illicit Unlock OXP (an old OXP introducing player versions of NPC ships, such as Vipers).

It can be downloaded from Box or from Oosat

Ideas

There a range of subentities which can be added to your ship/station -

• Weeviloid Hunter (Aegidian's demonstration OXP)
• Imperial Courier (Oolite) with revolving nacelles
• Ramon's Anaconda with docking bay doors
• Deep Space Dredger with docking bay door

• Z GrOovy HPC pack (Dertien - retractable landing gear & other goodies)
• Thargoid's writhing Stellar Serpents OXP & Animated Ships with flapping wings

• Transhab station (revolving rotor)
• Zieman's ZSuperIco station - revolving shells within shells
• Wildships (lifts moving inside the arms of some of the various stations)

You can also add personality!

• Missionaries OXP - 3 different OXP versions
• Hotrods OXP - gangs
• Refugee Adder - 3 different OXP versions
• BoyRacer - Bored, filthy-rich youths and their small fast luxury racers.
• Alien Systems OXZ - stations for non-human systems
• Solos Alt Stations - the newer 2022 versions have been re-imagined by Redspear

Subentities

Entities can have sub-entities, which are defined by quaternions. There are several types of SE:

• Model Entities: can be any model, with any properties.
• Turrets: are a specialised model entity.
• Flashers: blinking lights
• Exhausts: although they are defined seperate from subentities, they can be regarded as subentities.

One important thing to remember is that frangibility is defined for the main entity, not seperately for every SE.

Tool: Library MatFinder

Svengali wrote a special add-on for Library - "a helper to set and test materials entries" - which inter-alia enables locating the exhaust and weapons on your ship model.

You need Library loaded as well. A new development sub-heading will appear on your docked F4 screen which will allow you to choose any ship model loaded and to analyse it.

Warning: this was cut and pasted here by an ignoramus who recognised its importance, but does not understand any of it!

Version 1.0

"It only works with the plain materials thing at the moment, because I wrote it to migrate from custom shaders to the default shader (as much as possible). Reason is that shader swapping is a 1st class performance killer and getting rid of a few custom shaders is surely a good thing. The tool also disables shaders in use to force use of Oolite's default shader, when the model gets shown on the main screens. It shows the shadered versions though when you can enter values. This is simply to show the difference between both version to give users a chance to get your material as close as possible to the 'original' version."

Multiple weapons are already supported, positions and orientations of subentities is on the to-do list.

Version 1.1

- Added note by a_c about gloss+specular

- Choices left aligned

- Handling for disallowed models via conditions

- Added Mode: Positions. Handling and logging for aft_eject_position, exhaust, missile_launch_position, scoop_position, view_position_aft, view_position_forward, view_position_port, view_position_starboard, weapon_position_aft, weapon_position_forward, weapon_position_port, weapon_position_starboard. The Positions mode requires shader support to visualize them.

- Testmode for view_positions

- Search for entity

For details & download link see the BB thread for his Library.oxp here or try MatFinder

Important comment from a_c

Decide what your ship should look like early on. Decide on the type of materials you need for each single part of it. Don't just go with it thinking that you just need to "dress it up" with a texture. If you do, it will most likely end up looking like the texture is a piece of coloured paper wrapped around a model. Some lighting and material tips (Another_commander 2020)

Links

• List of software - useful tools.
• RELOP and PROHIP: Retro Low Poly and Progressive High Poly
• The number of Polygons used to be an issue in the old days. See here for 2007.

For current advice see here (2023).

• Converter scripts - helpers for models and plists.

Cannot convert OBJ to DAT in both Win and Linux (2009)

Converting to .dat (2012)

• Materials_in_Oolite - further information about textures in Oolite.
• Explicit normals discussion (2009) - "face normals", smoothing etc.
• Quaternion
• Change Ship Size (Dimensions) (2011)
• Modifying a Model from 2009

Resources

• Top 5 Free Sci fi Kit Bashing Libraries (YouTube: 2018)
• SolCommand: Free download sci fi 3D models of spaceships, stations, weapons and other designs

Tutorials

• Modelling 101: Spreading the Wings of your Mind (2006) by Draco Caeles
• Indepth guide of ship concept creation for total idiots by Commander Xairon (of RXSoftware, 2012) with lively debate!
• noob: my own ship (2013+) - getting started!
• Some tips (2007) by Arexack
• Create New Model (2011) - see especially Dertien's post.
• YouTube classes in Wings3D (2013-4) by Dertien
• Newcomer and Possible New Ships (2014-15) by Jona - avoiding probable pitfalls
• Putting it all together (2018) by Phkb

Problems

• Moving Exhaust Trails (2024) - Exhaust trails which begin at the ship's /exhaust's surface can move when viewed externally, leaving a gap between the ship and the beginning of the trail.

Subentities (more advanced)

There are a number of oxp's featuring these:

• Z GrOovy HPC pack (2014) equipment appears on outside of ship when bought, and can be damaged in combat impairing its efficiency
• Refugee Adder (2006, XML) features a rotating rear-end
• Animated Ships (2010) has flapping wings
• stations - the docking bay for one thing - and some of the Kiota stations have moving escalators

Also, the original versions of Smiv's BattleDamage merged with Smivs' ShipSet to show hull damage on the ships.

Texturing

• OXP howto texture - texturing your new model