OXP howto model
- 1 Introduction
- 2 Which programme?
- 3 Create your model
- 4 Optimize
- 5 Export the model
- 6 Add model to OXP
- 7 Subentities
- 8 Tool: Library MatFinder
- 9 Important comment from a_c
- 10 Links
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)
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.
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.
If you've read the tutorial above it's time to think about a few more things.
Optimizing models and textures for a game is no fun, specially if it's a model with lots of greebles and funny details.
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).
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.
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.pyfrom 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).
Obj2DatTex.py still needs this version.
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
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: http://aegidian.org/bb/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.
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
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!
"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.
- - 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
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)
- 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.
- Materials_in_Oolite - further information about textures in Oolite.
- Change Ship Size (Dimensions) (2011)
- Top 5 Free Sci fi Kit Bashing Libraries (YouTube: 2018)
- SolCommand: Free download sci fi 3D models of spaceships, stations, weapons and other designs
- 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
- Putting it all together (2018) by Phkb
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.
- OXP howto texture - texturing your new model