Difference between revisions of "Find the culprit"

From Elite Wiki
(→‎The problem vanished)
(Edited)
 
(12 intermediate revisions by 2 users not shown)
Line 1: Line 1:
−
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  
+
[[File:Oolite-oxp-icon.png|right|300px]]
−
* the symptoms but also
+
Finding the one single OXP which is making your game go wrong!
 +
 
 +
== Overview ==
 +
In case you experience a "strange situation" in 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 Oolite version,
 
* which distribution and especially
 
* which distribution and especially
−
* which expansions  
+
* which expansions you have installed.
−
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 [https://en.wikipedia.org/wiki/Binary_search 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 805 expansions that currently are on the [https://github.com/OoliteProject/oolite-expansion-catalog expansion catalog]. Then only 10 tests should be sufficient to spot the one expansion causing a problem.
+
But you can do even more.  
  
−
= Prerequisite=
+
Here is a guide for troubleshooting, which should work if you track a problem in Oolite (core), with just one OXP/OXZ or in the incompatibility between several OXP/OXZs. Basically it is a [https://en.wikipedia.org/wiki/Binary_search binary search] in the installed OXP/OXZs. This allows, with a minimum of time spent, to test a large number of OXP/OXZs. Suppose you installed all the eight hundred-odd OXP/OXZs that currently are on the [https://github.com/OoliteProject/oolite-expansion-catalog expansion catalog]. Then only 10 tests should be sufficient to spot the one OXP/OXZ causing a problem.
  
−
* As you will be juggling a lot of expansions back and forth, find your directories where Addons and ManagedAddons are stored.
+
= Algorithm =
−
* 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.
+
== Prerequisite ==
  
−
= Validate Vanilla Oolite =
+
* Write a note reminding yourself of what went wrong - and of anything ''you'' might have done before the catastrophe.
 +
* As you will be juggling a lot of OXP/OXZs back and forth, [https://wiki.alioth.net/index.php/OXP#Locating_your_AddOns_folder find your folders] where your "Addons" (usually [[OXP]]s) and "ManagedAddons" ([[OXZs]]) are stored.
 +
* Create a backup of each of these folders.
 +
* Decide on a test procedure to check for the problem. Write it down. This could be to "load" a savegame, then fly to whatever star system, shoot a pirate and then check your cargo hold.
 +
 
 +
Once you have all this, 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 OXP/OXZs, (for example, by ''restarting'' a new game in "Strict mode"). Perform your test.
  
−
First, validate the problem does not occur in the core. For this, delete all expansions. Perform your test.
 
 
If the problem occurs, it is in the core. Congratulations, you can [https://github.com/OoliteProject/oolite/issues file an issue in the oolite github repository].
 
If the problem occurs, it is in the core. Congratulations, you can [https://github.com/OoliteProject/oolite/issues file an issue in the oolite github repository].
−
If it doesn't, the core is clean. Restore your expansions.
 
  
−
= Check Partition =
+
If it doesn't, the vanilla game code is clean. Restore your expansions.
 +
 
 +
== Binary Search of OXPs/OXZs ==
 +
=== Check Half of your OXP/OXZs ===
 +
 
 +
Create a list of all the installed OXP/OXZ's names and versions - you will need this. Oolite Starter can do this easily for you.
 +
 
 +
Remove 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 OXP/OXZ is left, and you still have not found the problem check the ''next'' section ("The problem vanished").
  
−
Create a list of all the installed expansions' names and versions - you will need them.
 
−
Delete half of them (in odd numbers 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.
 
Write down the list of those that are left.
 +
 
Run Oolite and perform your test.
 
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 re-occurs, an installed OXP/OXZ caused it. If that happened on the last one OXP/OXZ, you found it! Go to the Oolite bulletin board and ask for help. Otherwise repeat the "Check Half" 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 =
+
If the problem does not occur, it stems from the other half! Restore the OXP/OXZs from the other half and repeat the Check Half step.
  
−
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.
+
=== The problem vanished ===
  
−
Then it is likely the problem is caused by a combination of expansions that now got split over the two halfvs. Cut each half into two pieces again (now you have quarters).
+
While you were troubleshooting with some of your OXP/OXZs, all of a sudden the problem no longer occurred! Neither in the first half nor in the second half.
−
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.
+
 
 +
Then it is likely the problem is caused by a ''combination'' of OXP/OXZs that are now split between your 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 Half" step.
  
 
If it still doesn't, we have to switch the strategy.
 
If it still doesn't, we have to switch the strategy.
−
Restore the smallest combination of expansions that produces the problem.
+
 
 +
Restore the smallest combination of OXP/OXZs that produces the problem.
 +
 
 
Remove one and test again.  
 
Remove one and test again.  
 +
 
If the problem persists, repeat the step.
 
If the problem persists, repeat the step.
−
If the problem vanished, restore the deleted expansion and remove another one.
+
 
 +
If the problem vanished, restore the deleted OXP/OXZ 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.
 
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!
 
Good luck, Commander!
 +
 +
== Example Scenarios ==
 +
 +
=== Ben's problem in one OXP/OXZ ===
 +
Ben loves playing Oolite, and over time he accumulated a couple of OXP/OXZs. 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 a ship.
 +
 +
Ben has a problem in expansion C* (note the asterisk), but he does not know this. 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 doing anything else
 +
- Launch from the station and kill the next trader ship in the star system
 +
- Switch to the F5 screen and check the kill count afterwards
 +
- He expects to see his kill count increased by one
 +
 +
=== Validate Vanilla Oolite ===
 +
 +
As a first step, Ben removes all OXP/OXZs 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 Half (1) ===
 +
 +
*Ben creates the list of his OXP/OXZs: A, B, C*, D, E, F, G
 +
*Then he deletes half of the OXP/OXZs, 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 OXP/OXZ installed, so he repeats the "Check Half" step.
 +
 +
=== Check Half (2) ===
 +
 +
*Ben creates the list of his OXP/OXZs: A, B, C*, D
 +
*Then he deletes half of the OXP/OXZs, 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 OXP/OXZs installed the problem does not occur. He restores the OXP/OXZs from the other half (C*, D) and repeats the "Check Half" step.
 +
 +
=== Check Half (3) ===
 +
 +
*Ben creates the list of his OXP/OXZ: C*, D
 +
*Then he deletes half of the OXP/OXZ, 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 OXP/OXZ installed, so this one must be the culprit.
 +
 +
:Now Ben can go to the Oolite bulletin board and ask for help on OXP/OXZ C. The author of that OXP/OXZ is happy to hear his OXP/OXZ is getting used and fixes the bug in no time. Ben is happy, too.
 +
 +
== Sarah's problem between two OXP/OXZs ==
 +
Sarah is quite new to Oolite. Since she heard from Ben about the game she immediately installs several OXP/OXZs, 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 her 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 OXP/OXZs D# and K# (note 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 Half (1) ===
 +
 +
*Sarah creates the list of her OXP/OXZs: A, B, C, D#, E, F, K#
 +
*Then she deletes half of the OXP/OXZs, 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 OXP/OXZs installed the problem does not occur. She restores the OXP/OXZs from the other half (E, F, K#) and repeats the Check Half step.
 +
 +
=== Check Half (2) ===
 +
 +
*Sarah creates the list of her OXP/OXZs: E, F, K#
 +
*Then she deletes half of the OXP/OXZs, 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 OXP/OXZs installed the problem does not occur. See restores the OXP/OXZs from the other half (K#) and repeats the Check Half step.
 +
 +
=== Check Half (3) ===
 +
 +
*Sarah creates the list of her OXP/OXZs: K#
 +
*Then she deletes half of the OXP/OXZs (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 her checks of halves were successful, but has the problem really vanished?
 +
 +
=== The problem vanished ===
 +
 +
Sarah installs the counterpart of step 1, which is OXP/OXZs 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 half" 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 OXP/OXZs 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 gone
 +
 +
Test 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 OXP/OXZs D and K.
 +
 +
He goes to the Oolite bulletin board and asks for help. And learns that both OXP/OXZs implement a shuttle - but in incompatible ways.
 +
 +
So Ben tells Sarah to choose between D and K. Sarah is happy. The authors of OXP/OXZs D and K add an entry to their manifest.plist files so that the expansion manager knows about this incompatibility. This way future users will fall into the same pitfall.
 +
 +
[[Category:Help pages]]

Latest revision as of 20:34, 16 April 2026

Oolite-oxp-icon.png

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

Overview

In case you experience a "strange situation" in 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), with just one OXP/OXZ or in the incompatibility between several OXP/OXZs. Basically it is a binary search in the installed OXP/OXZs. This allows, with a minimum of time spent, to test a large number of OXP/OXZs. Suppose you installed all the eight hundred-odd OXP/OXZs that currently are on the expansion catalog. Then only 10 tests should be sufficient to spot the one OXP/OXZ causing a problem.

Algorithm

Prerequisite

  • Write a note reminding yourself of what went wrong - and of anything you might have done before the catastrophe.
  • As you will be juggling a lot of OXP/OXZs back and forth, find your folders where your "Addons" (usually OXPs) and "ManagedAddons" (OXZs) are stored.
  • Create a backup of each of these folders.
  • Decide on a test procedure to check for the problem. Write it down. This could be to "load" a savegame, then fly to whatever star system, shoot a pirate and then check your cargo hold.

Once you have all this, 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 OXP/OXZs, (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 Half of your OXP/OXZs

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

Remove 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 OXP/OXZ is left, and you still have not found the problem check the next section ("The problem vanished").

Write down the list of those that are left.

Run Oolite and perform your test.

If the problem re-occurs, an installed OXP/OXZ caused it. If that happened on the last one OXP/OXZ, you found it! Go to the Oolite bulletin board and ask for help. Otherwise repeat the "Check Half" step.

If the problem does not occur, it stems from the other half! Restore the OXP/OXZs from the other half and repeat the Check Half step.

The problem vanished

While you were troubleshooting with some of your OXP/OXZs, 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 OXP/OXZs that are now split between your 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 Half" step.

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

Restore the smallest combination of OXP/OXZs that produces the problem.

Remove one and test again.

If the problem persists, repeat the step.

If the problem vanished, restore the deleted OXP/OXZ 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 OXP/OXZ

Ben loves playing Oolite, and over time he accumulated a couple of OXP/OXZs. 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 a ship.

Ben has a problem in expansion C* (note the asterisk), but he does not know this. 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 doing anything else - Launch from the station and kill the next trader ship in the star system - Switch to the F5 screen and check the kill count afterwards - He expects to see his kill count increased by one

Validate Vanilla Oolite

As a first step, Ben removes all OXP/OXZs 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 Half (1)

  • Ben creates the list of his OXP/OXZs: A, B, C*, D, E, F, G
  • Then he deletes half of the OXP/OXZs, 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 OXP/OXZ installed, so he repeats the "Check Half" step.

Check Half (2)

  • Ben creates the list of his OXP/OXZs: A, B, C*, D
  • Then he deletes half of the OXP/OXZs, 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 OXP/OXZs installed the problem does not occur. He restores the OXP/OXZs from the other half (C*, D) and repeats the "Check Half" step.

Check Half (3)

  • Ben creates the list of his OXP/OXZ: C*, D
  • Then he deletes half of the OXP/OXZ, 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 OXP/OXZ installed, so this one must be the culprit.
Now Ben can go to the Oolite bulletin board and ask for help on OXP/OXZ C. The author of that OXP/OXZ is happy to hear his OXP/OXZ is getting used and fixes the bug in no time. Ben is happy, too.

Sarah's problem between two OXP/OXZs

Sarah is quite new to Oolite. Since she heard from Ben about the game she immediately installs several OXP/OXZs, 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 her 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 OXP/OXZs D# and K# (note 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 Half (1)

  • Sarah creates the list of her OXP/OXZs: A, B, C, D#, E, F, K#
  • Then she deletes half of the OXP/OXZs, 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 OXP/OXZs installed the problem does not occur. She restores the OXP/OXZs from the other half (E, F, K#) and repeats the Check Half step.

Check Half (2)

  • Sarah creates the list of her OXP/OXZs: E, F, K#
  • Then she deletes half of the OXP/OXZs, 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 OXP/OXZs installed the problem does not occur. See restores the OXP/OXZs from the other half (K#) and repeats the Check Half step.

Check Half (3)

  • Sarah creates the list of her OXP/OXZs: K#
  • Then she deletes half of the OXP/OXZs (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 her checks of halves were successful, but has the problem really vanished?

The problem vanished

Sarah installs the counterpart of step 1, which is OXP/OXZs 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 half" 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 OXP/OXZs 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 gone

Test 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 OXP/OXZs D and K.

He goes to the Oolite bulletin board and asks for help. And learns that both OXP/OXZs implement a shuttle - but in incompatible ways.

So Ben tells Sarah to choose between D and K. Sarah is happy. The authors of OXP/OXZs D and K add an entry to their manifest.plist files so that the expansion manager knows about this incompatibility. This way future users will fall into the same pitfall.

Retrieved from "https://wiki.alioth.net/index.php?title=Find_the_culprit&oldid=88413"