WorldScannerBuilder
com.jsmacrosce.jsmacros.client.api.classes.worldscanner.WorldScannerBuilder
Builds scanners with separate block and block-state filters. Named-method and string filters run in the scanner's native filtering path. A filter step starts with a with, and, or, or xor method and is completed by a comparison call; not immediately negates the complete existing filter. A second with filter replaces the existing filter in that category, while the other operators combine with it. A pending step must be completed before another starts.
String filters inspect the helper's complete toString() text, and each supplied pattern is an alternative. matches(String[]) uses whole-string regular-expression matching; the other string operations compare literal text. Use a named-method filter such as withBlockFilter(String) with "getId" to compare a method's returned value instead.
For example, this finds blocks whose helper text contains _ore or _block:
js
// matches applies each regular expression to the complete helper text
const ores = World.getWorldScanner()
.withStringBlockFilter().matches(".*_ore.*")
.orStringBlockFilter().matches(".*_block.*")
.build();
Chat.log(`${ores.scanAroundPlayer(2).size()} ore or building blocks`);Named-method filters accept public no-argument methods on BlockStateHelper or BlockHelper, except methods declared by Object; their return values must be numeric, String, or boolean. Numeric comparisons use an operator and a value, String comparisons use a comparison name and text, and boolean comparisons take the expected value. For more complex filters, use FWorld.getWorldScanner(MethodWrapper, MethodWrapper).
Constructors
new WorldScannerBuilder
Creates a builder with no block or block-state filters; scanners built without adding filters accept all blocks and states.
Methods
andBlockFilter
Starts a named-method block filter to AND with the existing block filter. Complete it with is(Object[], Object[]) or a string comparison; both filters must accept the block. Completion fails if no block filter exists.
// Both comparisons are numeric; both conditions must accept the block
const scanner = World.getWorldScanner()
.withBlockFilter("getHardness").is(">=", 10)
.andBlockFilter("getBlastResistance").is(">", 1200)
.build();
Chat.log(`${scanner.scanAroundPlayer(2).size()} hard and blast resistant blocks`);Parameters:
method: the name of a public no-argument method available on BlockHelper
Returns: this builder, for chaining
andStateFilter
Starts a named-method state filter to AND with the existing state filter. Complete it with is(Object[], Object[]) or a string comparison; both filters must accept the state. Completion fails if no state filter exists.
// getLuminance returns a number, so its comparison takes an operator and a number
const scanner = World.getWorldScanner()
.withStateFilter("isToolRequired").is(false)
.andStateFilter("getLuminance").is("==", 15)
.build();
Chat.log(`${scanner.scanAroundPlayer(2).size()} unbreakable fully lit states`);Parameters:
method: the name of a public no-argument method available on BlockStateHelper
Returns: this builder, for chaining
andStringBlockFilter
Starts a string block filter to AND with the existing block filter. Complete it with a string comparison; both filters must accept the block. Completion fails if no block filter exists.
Returns: this builder, for chaining
andStringStateFilter
Starts a string state filter to AND with the existing state filter. Complete it with a string comparison; both filters must accept the state.
Returns: this builder, for chaining
build
Builds a scanner using the completed filters and the client's current level. An unset filter category is unfiltered; the builder's filters are retained, so it can build multiple scanners.
// a block filter and a state filter are two independent stages, so a
// block that is hard enough and a state that needs no tool is one set
// of blocks rather than two alternative ones
const scanner = World.getWorldScanner()
.withBlockFilter("getHardness").is(">=", 10)
.withStateFilter("isToolRequired").is(false)
.build();
const found = scanner.scanAroundPlayer(2);
Chat.log(`${found.size()} hard blocks that break without a tool`);Returns: a scanner over the client's current level
contains
Completes a pending string filter by keeping a candidate when its text contains any supplied pattern as a literal substring. The candidate text is the helper's string form, and the patterns are alternatives; use matches(String[]) for regular-expression matching.
Parameters:
args: the substrings to look for in the text, at least one of which has to be found for a candidate to be kept
Returns: this builder, for chaining
endsWith
Completes a pending string filter, keeping a candidate when its helper text ends with any supplied suffix. The patterns are alternatives and are matched against the complete helper string, not a named method's return value.
Parameters:
args: the suffixes the text has to end with, at least one of which has to match for a candidate to be kept
Returns: this builder, for chaining
equals
Completes a pending string filter by keeping a candidate when its text equals any supplied pattern. The candidate text is the helper's string form, not just an identifier; an empty pattern list therefore matches nothing.
Parameters:
args: the patterns to compare the text against, at least one of which has to be equal for a candidate to be kept
Returns: this builder, for chaining
is
Completes the pending named-method filter using
args as the comparison arguments. Boolean and character methods take one value; String and numeric methods take two (a comparison name or operator, then a value). Numeric operators are interpreted when candidates are tested, so an invalid operator rejects candidates rather than failing at construction. // is(">=", 10) is the whole argument list: an operator and a number,
// because getHardness returns a float
const scanner = World.getWorldScanner()
.withBlockFilter("getHardness").is(">=", 10)
.build();
Chat.log(`${scanner.scanAroundPlayer(2).size()} blocks of hardness 10 or more`);Parameters:
args: the arguments for the comparison, whose count and types are decided by the return type of the method the pending step named
Returns: this builder, for chaining
Completes the pending named-method filter, passing
methodArgs to that method and filterArgs to its comparison. The helpers' eligible methods take no arguments; use is(Object[]) to supply comparison arguments for those methods.Parameters:
methodArgs: the arguments to call the named method with, ornullfor nonefilterArgs: the arguments for the comparison, whose count and types are decided by the return type of the named method
Returns: this builder, for chaining
matches
Completes a pending string filter, keeping a candidate when its complete helper text matches any supplied regular expression. Patterns are alternatives; matching is against the whole text rather than a substring search. Use contains(String[]) for literal substrings.
Parameters:
args: the regular expressions the whole text has to match, at least one of which has to match for a candidate to be kept
Returns: this builder, for chaining
notBlockFilter
Immediately negates the entire existing block filter. This completes within this call and throws if no block filter exists or another start step is pending.
Returns: this builder, for chaining
notStateFilter
Immediately negates the entire existing state filter, keeping states it rejected. It takes no method name and throws if no state filter exists or another start step is pending.
// Negate the completed state filter
const scanner = World.getWorldScanner()
.withStateFilter("exceedsCube").is(false)
.notStateFilter()
.build();
Chat.log(`${scanner.scanAroundPlayer(2).size()} states that are not full cubes`);Returns: this builder, for chaining
orBlockFilter
Starts a named-method block filter to OR with the existing block filter. Complete it with is(Object[], Object[]) or a string comparison; the method's return type determines the comparison arguments. Completion fails if no block filter exists.
Parameters:
method: the name of a public no-argument method available on BlockHelper
Returns: this builder, for chaining
orStateFilter
Starts a named-method state filter to OR with the existing state filter. Complete it with is(Object[], Object[]) or a string comparison; either filter may accept the state. Completion fails if no state filter exists.
// getId returns a string, so compare it with a string operation and value
const scanner = World.getWorldScanner()
.withStateFilter("isSolid").is(true)
.orStateFilter("getId").is("ENDS_WITH", "torch")
.build();
Chat.log(`${scanner.scanAroundPlayer(2).size()} solid states or torches`);Parameters:
method: the name of a public no-argument method available on BlockStateHelper
Returns: this builder, for chaining
orStringBlockFilter
Starts a string block filter to OR with the existing block filter. Complete it with a string comparison; either filter may accept the block. Completion fails if no block filter exists.
Returns: this builder, for chaining
orStringStateFilter
Starts a string state filter to OR with the existing state filter. Complete it with a string comparison; either filter may accept the state.
Returns: this builder, for chaining
startsWith
Completes a pending string filter, keeping a candidate when its helper text starts with any supplied prefix. The patterns are alternatives; they are matched against the complete helper string, not a named method's return value.
Parameters:
args: the prefixes the text has to begin with, at least one of which has to match for a candidate to be kept
Returns: this builder, for chaining
test
Alias of is(Object[]) for languages in which
is is a keyword. This alias is not exposed by the typed builder returned by World.getWorldScanner().Parameters:
args: the arguments for the comparison, whose count and types are decided by the return type of the method the pending step named
Returns: this builder, for chaining
Alias of is(Object[], Object[]) for languages in which
is is a keyword. No helper method accepts arguments, so this overload has no useful named-method arguments; it is also absent from the typed builder returned by World.getWorldScanner().Parameters:
methodArgs: the arguments to call the named method with, ornullfor nonefilterArgs: the arguments for the comparison, whose count and types are decided by the return type of the named method
Returns: this builder, for chaining
withBlockFilter
Starts a block filter on a named method; complete it with is(Object[], Object[]) or a string comparison. Invalid method names and comparison arguments are checked during completion. Starting another step while one is pending throws
IllegalStateException. A block filter and a state filter are two independent stages rather than alternatives, so a state filter set afterwards narrows the block filter rather than replacing it. // getHardness returns a number, so its comparison takes an operator and a number
const scanner = World.getWorldScanner()
.withBlockFilter("getHardness").is(">=", 10)
.build();
const found = scanner.scanAroundPlayer(2);
Chat.log(`${found.size()} blocks with a hardness of 10 or more`);Parameters:
method: the name of a public no-argument method available on BlockHelper, and the arguments the following is(Object[], Object[]) needs are decided by its return type
Returns: this builder, for chaining
withStateFilter
Starts a block-state filter using a named helper method. Complete it with a comparison call; the completed
with filter replaces any existing state filter. A pending filter step prevents another from starting. // A boolean-returning method takes the expected value as its comparison
const scanner = World.getWorldScanner()
.withStateFilter("isToolRequired").is(false)
.build();
const found = scanner.scanAroundPlayer(2);
Chat.log(`${found.size()} states that break without a tool`);Parameters:
method: the name of a public no-argument method on BlockStateHelper
Returns: this builder, for chaining
withStringBlockFilter
Starts a block filter that compares the block helper's complete
toString() text. Complete it with equals(String[]), contains(String[]), startsWith(String[]), endsWith(String[]) or matches(String[]).Returns: this builder, for chaining
withStringStateFilter
Starts a block-state filter that compares the state helper's complete
toString() text, including its property map. Complete it with equals(String[]), contains(String[]), startsWith(String[]), endsWith(String[]) or matches(String[]).Returns: this builder, for chaining
xorBlockFilter
xorBlockFilter(String method): WorldScannerBuilder#Starts a named-method block filter to XOR with the existing block filter. Complete it with a comparison call; exactly one constituent must accept. The method's return type determines the comparison arguments. Completion fails if no block filter exists.
Parameters:
method: a public no-argument method, including inherited methods
Returns: this builder for chaining
xorStateFilter
xorStateFilter(String method): WorldScannerBuilder#Starts a named-method state filter to XOR with the existing state filter. Complete it with is(Object[], Object[]) or a string comparison; exactly one filter must accept the state. Completion fails if no state filter exists.
Parameters:
method: the name of a public no-argument method available on BlockStateHelper
Returns: this builder for chaining
xorStringBlockFilter
xorStringBlockFilter(): WorldScannerBuilder#Starts a string block filter to be XORed with the existing block filter. Complete it with a string comparison; exactly one constituent must accept.
Returns: this builder for chaining
xorStringStateFilter
xorStringStateFilter(): WorldScannerBuilder#Starts a string state filter to be XORed with the existing state filter. Complete it with a string comparison; exactly one constituent must accept.
Returns: this builder for chaining