Seed search requirements

requirements/seed-search-notes.txt

@@ -0,0 +1,7 @@
+* add CLI
+* terminology: replace "report" by "ignore"?
+* use array shorthand for and?
+* check for cyclic dependencies
+* don't calculate score for "and" and "or" by adding the childrens score by default, because it prevents the short-circuiting
+* if another criterion is refered to use its position, make sure it has a position property -> should be obsolete now, that we dropped the relative center point feature
+* score that is calculated based on the match location (e.g. distance from the center) -> prevents filter from short-circuiting, because there might always be a better match -> filters have a findAnyMatch and findAllMatches operation?

requirements/seed-search-structure-alt.md

@@ -0,0 +1,96 @@
+THIS IS A DRAFT
+
+**Note:** The behavior described here is likely to be a superset of what will be available to the user (but the internal structures should support all these operations).
+
+**TODO:**
+- number of structures feature in criteria (should constraints returns multiple coordinates for reporting multiple structures?)
+- score/result propagation for criterion references
+
+### World
+Consists of:
+- a minecraft version
+- a seed
+- a world generator (i.e. a world type)
+- world generator options (optional)
+- a center point (all coordinates and areas will be taken relative to this center point)
+
+
+### Predicate
+Given a world and a coordinate, returns whether the coordinate satisfy a condition.
+
+**Example:**
+- being in a given biome
+- being the center of a given structure
+- being inside a given area (square, circle, etc)
+- combinations of the above
+
+**Note:** For ease of implementation, only predicates of the form `(biome1 OR ... OR biomeN) AND (structure1 OR ... OR structureN) AND area` will be expressible.
+
+
+### Valuation
+Given a coordinate, returns a positive value (higher is better)
+
+**Example:**
+- a constant valuation
+- a higher valuation when the coordinate is closer to a given center point
+
+### Constraint
+Consists of:
+- a Predicate
+- a Valuation
+
+Given a world, find among the coordinates which satisfy the predicate the one with maximum valuation, and returns it (along with its valuation). If more than one coordinate have maximum valuation, only one will be returned. If no coordinate satisfy the predicate, the constraint returns nothing.
+
+**Short-circuiting:** When evaluating the constraint, we can stop testing coordinates as soon as we know that no non-tested coordinate will have a better valuation than the current one. (e.g. if the valuation is constant, we can return the first coordinate we find)
+
+
+### Criterion
+Given a world, returns whether or not it matches a certain condition.
+If it matches, returns the resulting score (a positive number), and a list of matched constraints, along with their result.  
+In addition to the score calculation specific to each type, a criterion also has an optional `score` attribute, whose value will be added to the score of the criterion if it matches.
+
+The different type of criteria are:
+
+
+#### A Constraint
+A Constraint can be "lifted" to a criterion.
+The criterion matches iff the constraint returns a coordinate, and its score is the valuation of this coordinate.
+
+
+#### A reference to another criterion
+Matches iff the specified criterion matches.
+TODO decide how to propagate score/result
+
+#### A Negation of another criterion
+Matches iff the specified criterion DOES NOT match.
+If it matches, ignore the result returned by the inner criterion, and return and empty match list, with a score of 0.
+
+**Short-circuiting:** As the matches and the score of the inner criterion are ignored, we can abord as soon as the inner criterion is garanteed to match.
+
+
+#### An `and` criterion
+Consists of: 
+- a list of children criteria
+
+Matches iff all of its children match, and returns the results of all of its children; the score is the sum of the scores of all children.
+
+**Short-circuiting:** If one children criterion doesn't match, we can immediately abort and say the `and` criterion doesn't match.
+
+
+#### An `or` criterion
+Consists of:
+- a list of children criteria
+- two optional attributes `min` and `minScore` (which are positive numbers, 0 by default)
+
+Matches iff at least `min` children matches AND the sum of their scores is at least `minScore`. Only use criteria with a score of 0 if it is required for the criterion to match.
+
+Returns the results of all of the matched children; the score is the sum of the score of all of the matched children.
+
+**Short-circuiting:** If there is not enough untested criteria for the `or` to match, we can immediately abort. Also, we only test the criteria with a score of 0 only after testing all the others (and the `or` still hasn't matched).
+
+
+### Search Query
+TODO
+
+### Seed List
+TODO

requirements/seed-search-structure.txt

@@ -0,0 +1,103 @@
+* the user can divide a set of search seeds into a set of matching seeds and a set of unmatching seeds by using a search query. For this, the user provides
+  * a set of search seeds
+  * a search query
+  * additional information
+
+* a search seed consists of
+  * a minecraft version
+  * a world type
+  * a seed
+  * a search area
+
+* a search area consists of
+  * a center point
+  * a size
+  * a shape (optional)
+
+* a set of search seeds can be given by
+  * a set of search seeds
+  * a search-seed-generator
+
+* a search-seed-generator
+  * is identified by its name
+  * receives a map of strings as parameters (optional)
+  * returns a set of search seeds, one at a time
+
+* a search query consists of
+  * a name-indexed map of search criterions
+  * a matching condition
+  * a set of report-criterions
+
+* a search criterion consists of
+  * a filter
+  * a score
+
+* a filter
+  * is one of
+    * a biome filter
+    * a structure filter
+    * a logic filter
+  * receives its search area from the search criterion
+
+* a biome filter
+  * consists of
+    * a set of biomes
+    * a search area (optional)
+    * a minimal size (optional)
+    * a shape (optional)
+  * matches a search seed, iff the search seed contains an area in the search area that matches all of the following
+    * it contains only biomes from the given set of biomes
+    * it has at least the given size
+    * it has the given shape
+
+* a structure filter
+  * consists of
+    * a set of structure types
+    * a search area (optional)
+    * a minimal number of structures (optional)
+    * a shape (optional)
+  * matches a search seed, iff the set of structure from the search seed, which are located in the search area contain a subset of structures that matches all of the following
+    * it contains only structures with a type from the given set of structure types
+    * it has at least the given number of structures
+    * it has the given shape
+
+* a logic filter
+  * consists of
+    * a criterion-operation
+    * a set of search criterions
+  * matches a search seed, iff the operation (parameterized with the given search criterions) matches
+
+* a criterion-operation
+  * is identified by its name
+  * receives a list of strings as parameters (optional)
+  * receives a set of search criterions
+  * can use all properties of the search criterions
+  * returns a boolean value (matches or matches not)
+
+* a score can be
+  * a fixed number
+  * a score-operation
+
+* a score-operation
+  * is identified by its name
+  * receives a list of strings as parameters (optional)
+  * receives a filter
+  * can use all properties of the filter
+  * returns a score value
+
+#* the center point of a search area can be given by
+#  * a fixed coordinate
+#  * a coordinate-operation
+#
+#* a coordinate-operation
+#  * is identified by its name
+#  * receives a list of strings as parameters (optional)
+#  * receives a list of coordinates
+#  * returns a coordinate
+#
+#* a coordinate for the coordinate-operation can be one of
+#  * "spawn" for the spawn point
+#  * the name of a criterion for the ...
+
+an example score-operation is one that has a higher score when the matched structure is near to the center point. note, that this prevents the filter from short-circuiting
+examples for a criterion-operation are "and", "or", "not", "minimal score" and "minimal number of matches"

requirements/seed-search.txt

@@ -0,0 +1,77 @@
+1 the user can query whether a specific biome exists in a given radius around a given coordiate
+1.1 the user can specify a minimal biome size
+1.2 the user can query for a set of biomes, it matches if any of the biomes in the set is found
+1.3 the user can specify the shape of the biome
+1.4 the distance of the match is used to calculate the match quality
+
+2 the user can query whether a specific structure exists in a given radius around a given coordiate
+2.1 the user can specify a minimal number of structures
+2.2 the user can query for a set of structures, it matches if any of the structures in the set is found
+2.3 the user can specify the layout if multiple structures are matched
+2.4 the distance of the match is used to calculate the match quality
+
+3 the user can exclude seeds that match a given criterion
+
+4 the user can terminate the search at any time
+4.1 the user can tell how well the searched seeds matched the query
+4.2 the user can tell how long it takes to find a perfect match (pre-calculated average times foreach combination of minecraft version, biome and structure)
+
+5 the user can see a history of previous searches
+5.1 the user can execute previous search again
+
+6 the user can search for commonly known "good" seeds
+6.1 the user can search for a quad witch hut
+
+7 the user can add different weights to different parts of the query, these weights are used to determine the quality of the match, but before this the seed has to match
+
+8 the user can run multiple independent queries at the same time
+
+9 the user can specify exactly where to search
+9.1 the user can specify the world type
+9.2 the user can specify the world seed
+9.3 the user can specify the minecraft version (might need to use the launcher profile name)
+9.4 the user can specify the center
+9.5 the user can specify the shape of the search area (circle vs square)
+9.6 the user can specify a list of seeds different values for 9.1 - 9.5
+9.7 the user can specify to use random seeds with 9.1, 9.3, 9.4 and 9.5 as fixed values
+9.8 the user can specify a seed generator (e.g. all seeds starting from a given seed)
+
+10 the user is able to tell why a given seed was accepted or rejected
+10.1 the user can tell which of the criteria was checked, matched and unmatched
+10.2 additional information are always present, if the seed matched
+
+11 the user can write sub-queries that work relative to the position of another query match
+
+12 the user is not limited by arbitrary size restrictions (512 blocks raster)
+
+13 each criterium can have a different center point and shape
+13.1 the center point can be a fixed coordinate
+13.2 the center point can be given relative to another coordinate, which can be one of
+13.2.1 "center" for the center point of the seed
+13.2.2 "spawn" for the world spawn point of the seed
+13.2.3 "origin" for the coordinate [0, 0]
+13.2.4 another explicitly given coordinate
+13.2.5 the coordinate of an already matched criterium
+
+14 the search should be as quick as possible
+14.1 the search can be executed on multiple threads
+14.2 only the necessary biome data should be generated
+14.3 the necessary biome data should be generated only once
+14.4 a unmatching seed should be rejected as soon as possible
+14.5 a matching seed should be accepted as soon as possible
+14.6 for a matching seed, we still need to collect all additional information
+14.7 we can optimise the query so we execute the parts that are likely to terminate the matching algorithm early e.g. we can execute cheap sub queries early on and use the logical structure of the query
+
+15 the user can figure out how to write a query
+15.1 there is documentation about the query syntax
+15.2 if an invalid query is entered, the user receives a meaningful error message
+
+16 the user can specify when the search should be terminated
+16.1 the user can specify to search for one matching seed
+16.2 the user can specify to search through all seeds of a finite list
+16.3 the user can specify to search through the seeds of an infinite list until he stops manually
+16.4 the user can specify to search through the seeds of an infinite list until a given number of seeds has been checked
+16.5 the user can specify to search through the seeds of an infinite list until a given number of seeds has been found
+16.6 the user can specify to search through the seeds of an infinite list until a given timeout is reached
+
+17 the user can collect additional information about a seed that already matched the query