Ruleset Debugging

== Debugging with the Freeciv server ==
The Freeciv server is responsible for loading and enforcing the rules during a game. It can do more than just load your ruleset to allow you to test it by hand.
=== Errors ===
The Freeciv server will refuse to load a ruleset with an error. While doing so it will hopefully print a useful error message that helps you find the problem.
=== Other issues ===
The Freeciv server has a warnings mode. This will print warnings about other issues like the use of deprecated functionality. Start the Freeciv server with the --warnings option to see them.
== Debugging with Ruledit ==
Ruledit is a ruleset editor.
=== Errors ===
Ruledit will ask for confirmation before saving a ruleset with an error. From 3.0 some action enabler errors can be repaired by selecting the action enabler, pushing the "Repair Enabler" button and applying the suggested solution.
=== Other issues ===
From 3.0 some action enabler issues can be improved by selecting the action enabler, pushing the "Improve Enabler" button and applying the suggested solution.
== Detecting never fulfilled requirement vectors ==
It is possible to write a requirement vector that never can be fulfilled. This can be cased by problems in the requirement vector itself or by interactions with other parts of the entity the requirement vector is attached to.
=== A requirement vector contradicting it self ===
A self contradiction in a requirement vector doesn't only happen if you require A and not A in the same vector. It can also happen when two requirements can't be fulfilled at the same time - like requiring both War and Peace in the local range.
Freeciv is able to detect some self contradicting requirements in requirement vectors. Freeciv 2.6 introduced some detection of self contradicting requirements beyond opposites.
=== An action enabler requirement vector contradicting the other requirement vector ===
An action enabler has two requirement vectors. One applies to the actor and the other to the target. A requirement in one requirement vector may accidentally contradict a requirement in the other requirement vector. Say that a tile targeted action requires that the actor has a cease fire with the target but also that the target tile is unclaimed.
Freeciv 3.0 introduces contradiction checks across action enabler requirement vectors. It is able to automatically detect some - but far from all - contradictions.
=== An enabler vector contradicting its action ===
A requirement in an action enabler vector may accidentally contradict a hard coded requirement for the action it self. This can happen if you don't pay close attention to an action's hard requirements or don't think of how the fulfillment of a requirement in your vector contradicts a hard requirement for the action it self.
Freeciv 3.0 introduces obligatory hard requirements for actions. An action's obligatory hard requirements are mandatory in all its action enablers. This makes each requirement explicit so Freeciv's automatic self contradiction detection has a chance of finding them. It is easier to manually detect self contradictions when they are explicit.
A hard requirement can only become an obligatory hard requirement if it can be represented in an action enablers requirement vector. A hard requirement that can be represented as a requirement can only become an obligatory hard requirement for its action in a version of Freeciv if it is added before the data file format freeze. Soft detection that suggests adding the hard requirement to an action enabler as an improvement can be added later.
== Detecting sub optimal rule expression ==
Many parts of Freeciv reasons about the ruleset. The help system writes automatic documentation based on the rules. The built in AI tires to find out what moves are legal and what their results will be. The clients adapt their user interface to the rules.
The ruleset reasoning code does not understand every way of expressing the same rule equally well. A non detected rule can disable features that would work if the same rule was expressed in a different way.
=== Requirement implications ===
The rule reasoning code can ignore the implications of a requirement being fulfilled. Say that an action enabler for a tile targeted action requires a local DiplRel to its target. This implies that the target tile must be claimed. Explicitly adding claimed as a requirement in the action enabler's target requirement vector makes it easier for Freeciv's reasoning code to detect that the tile must be claimed.
Freeciv 3.0 has some detection for implied requirements that could be added to action enabler requirement vectors in cases where doing so help Freeciv's reasoning about the rules.
Category:Editing rulesets