Find the culprit

Finding the one single OXP which is making your game go wrong!

Overview

In case you experience a strange situation with Oolite - and in case you want to talk to someone about this - it definitely helps others to describe not just

• the symptoms

but also

• which Oolite version,
• which distribution and especially
• which expansions you have installed.

But you can do even more.

Here is a guide for troubleshooting, which should work if you track a problem in Oolite (core), in one expansion or in the incompatibility between several expansions. Basically it is a binary search in the installed expansions. This allows with a minimum of test cycles to span a big number of expansions. Suppose you installed all the eight hundred-odd expansions that currently are on the expansion catalog. Then only 10 tests should be sufficient to spot the one expansion causing a problem.

Algorithm

Prerequisite

• As you will be juggling a lot of expansions back and forth, find your directories where Addons and ManagedAddons are stored.
• Create a backup of these directories.
• Decide for a procedure to check for the bug. Write it down. This could be to load a savegame, fly to whatever star system, shoot a pirate and then check your cargo hold.

Once you have that, you can start the troubleshooting loop.

Validate Vanilla Oolite

First, find out if the problem occurs in the Vanilla game code. For this, remove all expansions, (for example, by restarting a new game in "Strict mode"). Perform your test.

If the problem occurs, it is in the core. Congratulations, you can file an issue in the oolite github repository.

If it doesn't, the vanilla game code is clean. Restore your expansions.

Binary Search of OXPs/OXZs

Check Partition

Create a list of all the installed expansions' names and versions - you will need this. Oolite Starter can do this easily for you.

Delete half of them (if you have an odd number of them, then it does not matter whether you delete one more or less). If no expansion is left, and you still have not found the problem check the next section.

Write down the list of those that are left.

Run Oolite and perform your test.

If the problem occurs, the installed expansions caused it. If that happened on the last one expansion, you found it! Go to the Oolite bulletin board and ask for help. Otherwise repeat the Check Partition step.

If the problem does not occur, it stems from the other half. Restore the expansions from the other half and repeat the Check Partition step.

The problem vanished

While you were troubleshooting with partitions all of a sudden the problem no longer occurred. Neither in the first half nor in the second half.

Then it is likely the problem is caused by a combination of expansions that now got split over the two halves. Cut each half into two pieces again (now you have quarters).

Now combine the first half's first half with the second half's first half. Combine the remaining two halves, hoping the problem would show up with one of them. If it does, go back to the Check Partition step.

If it still doesn't, we have to switch the strategy.

Restore the smallest combination of expansions that produces the problem.

Remove one and test again.

If the problem persists, repeat the step.

If the problem vanished, restore the deleted expansion and remove another one.

This should bring you down to the least amount of expansions that - installed together - produce a problem. With that information go to the Oolite bulletin board and ask for help.

Good luck, Commander!

Example Scenarios

Ben's problem in one expansion

Ben loves playing Oolite, and over time he accumulated a couple of expansions. To stay simple we just call them with one letter each: A, B, C*, D, E, F, G

One day Ben discovers a strange, annoying behaviour. His ship kills counter does not increase reliably when he blows up some ship. Ben has a problem in expansion C* (note the asterisk), but he does not know. With no better plan in mind he finds this wiki page and starts applying the algorithm to find the culprit.

Prerequisite

Ben finds the folders for Addons in ~/Oolite/Addons and ~/Oolite/.ManagedAddons. He makes a backup copy of these folders. Also he writes down how to reproduce the bug: - Start Oolite - Load Savegame fifteen - Switch to the F5 screen and check the kill count before - Launch from the station and kill the next trader ship in the star system - Switch to the F5 screen and check the kill count after - It is expected to see the kill count increased by one

Validate Vanilla Oolite

As a first step, Ben removes all expansions from the ~/Oolite/Addons and ~/Oolite/.ManagedAddons folders. Then he performs the test, as written down above. And he can confirm that the kill count increases as expected. So Oolite itself is good, and the behaviour must have come from some expansion. But which one? He restores the files from his backup.

Check Partition (1)

Ben creates the list of his expansions: A, B, C*, D, E, F, G Then he deletes half of the expansions, so he is left with A, B, C*, D Then he performs the test, as written down above. And he can see the odd behaviour again. He has more than one expansion installed, so he repeats the Check Partition step.

Check Partition (2)

Ben creates the list of his expansions: A, B, C*, D Then he deletes half of the expansions, so he is left with A, B Then he performs the test, as written down above. And he can confirm that the kill count increases as expected. With the two expansions installed the problem does not occur. He restores the expansions from the other half (C*, D) and repeats the Check Partition step.

Check Partition (3)

Ben creates the list of his expansions: C*, D Then he deletes half of the expansions, so he is left with C* Then he performs the test, as written down above. And he can see the odd behaviour again. He has only one expansion installed, so this one must be the culprit.

Now Ben can go to the Oolite bulletin board and ask for help on expansion C. The author of that expansion is happy to hear his expansionn is getting used and fexes the bug in no time. Ben is happy, too.

Sarah's problem between two expansion

Sarah is quite new to Oolite. Since she heard from Ben about the game she immediately installs several expansions, though not the exact same set as Ben. To stay simple we just call them with one letter each: A, B, C, D#, E, F, K#

Sarah plays the game and gets frustrated. For some reason she cannot dock via the shuttle. When she presses the button the shuttle launches from her ship, but then she can see it going to various places, spending time, going elsewhere but just not to the station the way it works for Ben. She suffers an incompatibility between expansions D# and K# (mind the #) but nobody knows about it. With no better plan in mind Ben helps her find this wiki page and she starts applying the algorithm to find the culprit.

Prerequisite

Sarah finds the folders for Addons in ~/Oolite/Addons and ~/Oolite/.ManagedAddons. She makes a backup copy of these folders. Also she writes down how to reproduce the bug: - Start Oolite - Load Savegame blueberry - Launch from the station, fly a curve and stop. - Activate the shuttle to dock again - The shuttle is expected to dock at the station within 120 seconds.

Validate Vanilla Oolite

As a first step, Sarah removes all expansions from the ~/Oolite/Addons and ~/Oolite/.ManagedAddons folders. Then she performs the test. Actually she tries to. But there is no shuttle in vanilla Oolite. So Oolite itself is good, and the behaviour must have come from some expansion. But which one? She restores the files from her backup.

Check Partition (1)

Sarah creates the list of his expansions: A, B, C, D#, E, F, K# Then she deletes half of the expansions, so she is left with A, B, C, D# Then she performs the test, as written down above. And can see the shuttle docking in good time. With the four expansions installed the problem does not occur. See restores the expansions from the other half (E, F, K#) and repeats the Check Partition step.

Check Partition (2)

Sarah creates the list of his expansions: E, F, K# Then she deletes half of the expansions, so she is left with E, F Then she performs the test. Actually she tries to. But there is no shuttle any more. With the two expansions installed the problem does not occur. See restores the expansions from the other half (K#) and repeats the Check Partition step.

Check Partition (3)

Sarah creates the list of his expansions: K# Then she deletes half of the expansions (give or take 1), so she is left with K# Then she performs the test, as written down above. And can see the shuttle docking in good time. All partitions were successful, the problem vanished?

The problem vanished

Sarah installs the counterpart of step 1, which is expansions E, F, K# and verifies the problem is gone. What next? It takes her a while to understand mixing the halves, so she comes up with

• the full list: A, B, C, D#, E, F, K#
• Split 1: A, B, C, D# | E, F, K#
• Split 2: A, B | C, D# || E, F | K#

Then she swaps halves from split 2 and gets

• Swap: A, B | K# || E, F | C, D#

With that she goes back to the check partition step. But regardless whether she tests A, B, K# or the counterpart E, F, C, D# the problem does not occur. Sarah is desperate, so Ben takes over and changes the strategy. He removes expansions one by one to find the culprit.

Test A, B, C, D#, E, F, K#: Problem occurs

Test B, C, D#, E, F, K#: Problem occurs

Test C, D#, E, F, K#: Problem occurs

Test D#, E, F, K#: Problem occurs

Test E, F, K#: Problem is gone

Ben restores D# and deletes some other expansion

Test D#, F, K#: Problem occurs

Test D#, K#: Problem occurs

Test D#: Problem is goneTest C, D#, E, F, K#: Problem occurs

Just to be sure, Ben also tests the counterpart:

Test K#: Problem is gone

Now Ben is sure: There is something going on between expansion D and K.

He goes to the Oolite bulletin board and asks for help. And learns that both expansions implement a shuttle - but in incompatible ways. So Ben tells Sarah to choose between D and K. Sarah is happy. The authors of expansions D and K add an entry to their manifest.plist files so any expansion manager knows about this incompatibility. This way future users will not go into the same pitfall.