Welcome back to my blog series on implementing procedurally-generated map compasses! Last time I completed the implementation of the Lodestone rules engine that is able to read an execute rules like these:
<$pi> => `Math.PI`; <start> => <first> [1] | <second> [`99+99`]; <first> => I'm surprised this was selected!; <second> => The value of pi is <$pi>;
But entering these rules as a Javascript string is painful, so today I'm going to start off by building a little utility that will read in a file of rules and prepare them for use.
But there's one -- or really two -- complications when you try to read a file from the browser. For security reasons, Javascript running in the browser is not permitted to read in files. This makes sense -- you don't want some random website looking around on your computer for MyPasswords.txt or any other sensitive information. What the browser is allowed to do is read any file or web page it can reach with a URL. So the browser can't read a file of rules from the local directory, but it can read the same file from a web server. This is why this project is set up to use the Mongoose web server. The code can ask the web server to give it files that are located in the project directory, such as a file of rules or a local font file.
So the first complication is that we have to get to the rules file through the web server rather than loading it directly. The second complication is that the browser mechanism for fetching a file this way works asynchronously, meaning it doesn't wait around for the file to be fetched, it just promises to let you know later when it's done. There are actually two asynchronous steps to this process. Let me start with the first and easiest step -- fetching the contents of the URL as a “blob."
To do that, I use the browser's fetch() function, which takes a URL and fetches the contents of the URL. In this case, the URL is just the name of the file with the rules in it. Since this file is in the same directory as the file with the Javascript, I can use this sort of relative URL. The .then() method is executed when the fetch completes, and takes the result (which has a bunch of information) and pulls off the “blob." The details of the blob aren't important; it's just an internal format that could be text, an image, or anything else that could be fetched by URL.// Gets the response and returns it as a blob let blob = await fetch('compass.rules').then(res => res.blob());
But since fetch is an asynchronous function, it returns immediately, before it has fetched anything and before the then() has pulled out the blob. The purpose of the await keyword in front of the fetch is to force the Javascript engine to stop and wait for the fetch (really the then) to complete. So in effect, the await keyword turns the asynchronous function into a synchronous function.
Now I need to turn the blob into text. Javascript provides a mechanism to do this called a FileReader, which has a method readAsText that takes a blob and returns text. Or at least it eventually returns text, because like fetch, FileReader is asynchronous. You might think then that I could use await like this:
const compassRulesReader = new FileReader(); const text = await compassRulesReader.readAsText(blob);
But this would be too easy. You see, await is built on something called Promises, and FileReader is from before Promises were added to Javascript. So it uses an older and uglier way to accomplish the same thing, something called event handlers. Fortunately, it is possible to wrap FileReader in a Promise so that it can be used with await. I won't show that code here -- you can see it at the link above or in the compass.js file. But with that wrapper in place I can write:
const blob = await fetch('compass.rules').then(res => res.blob()); const text = await readText(blob);
And at the end of that, text holds the text of the compass.rules file. I can put these two awaits together and put this at the top level of the compass module as so:
const compassRulesText = await fetch('compass.rules') .then(res => res.blob()) .then(blob => readText(blob));
When you put an await at the top level of a module like this, you essentially pause the loading of the module until the await completes. In this case, that's fine, but in many cases you want to avoid doing that so that you can immediately use the parts of the module that aren't waiting.
Now that I have the text of the compass.rules file, I can prepare those rules and then execute them to create a compass description in CDL and pass it to the interpreter:
function test(svg) { const rules = prepareLodestone(compassRulesText); const cdl = executeRules('<compass>', rules, s => eval(s)); const result = interpretCDL(svg, parseCDL(cdl, true), [100,100], 75, true); };
Of course, I'll need to actually have some rules in compass.rules that will produce a compass :-) so let me start in on that. (Finally! We've been waiting!) In the past posts I've used these two compasses as examples:
To begin with, I'll put together rules to produce the left-hand example.
<compass> => <twoLayerCompass>; <twoLayerCompass> => <bottomLayer> <topLayer>; <bottomLayer> => SPACE(23) <ring>; <ring> => <thickCircle> SPACE(3) <thinCircle>; <thickCircle> => CIRCLE(<$thickWidth>, "black", "none"); <thinCircle> => CIRCLE(<$thinWidth>, "black", "none"); <$thickWidth> => 4 | 3.5 | 3; <$thinWidth> => 1.5 | 1 | 0.5; <topLayer> => <interCardinalPoints> <cardinalPoints>; <interCardinalPoints> => RPOINT(0.7854, 4, 0.85, 1, 1, "black", "white", "black"); <cardinalPoints> => SPACE(-22) RPOINT(0, 4, 0.85, 1, 1, "black", "white", "black");
This reproduces something fairly close to the example compass above, but that's all it can do. It's stuck at Level 0 of procedural generation, only able to produce one object. But by individually generalizing the parameters in these rules I can transform this into a Level 1 procedural generator.
Let's start with a single rule:
<bottomLayer> => SPACE(23) <ring>;
How can I generalize this rule to increase the space of compasses it produces? The obvious first candidate is to turn the specific 23 pixel space into a range of possible spaces. It isn't immediately obvious what a reasonable range is, but I can write the rule and try it out to narrow down. To pick a random range of values I could write a rule like this:
distance => 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27;
But those sorts of rules get tedious very quickly, so I prefer to use the embedded Javascript capability to have Javascript generate a random number in a range:
<bottomLayer> => SPACE(`Math.random()*40+10`) <ring>;In this case in the range from 10 to 50. It's handy to have some utility functions to deal with random numbers, so I've included some in utils.js and I'll use one here instead of Math.random:
<bottomLayer> => SPACE(`Utils.randIntRange(10,50)`) <ring>;This function generates an random integer in the given range. But rather than moving the ring in closer or farther away from the center, this seems to grow or shrink the whole compass:
<cardinalPoints> => SPACE(-22) RPOINT(0, 4, 0.85, 1, 1, "black", "white", "black");
The SPACE(-22) here is intended to undo the SPACE(23) in the <bottomLayer> rule. But when the value in that rule isn't 23, everything breaks.
There are a number of ways you might fix this. But I think what's really needed here is a method in CDL to remember a location and return to it later. I implemented a version of this for MBDL called PUSH and POP that let you return to the last location you had remembered. But for CDL I think it will be better to have the capability to remember and return to multiple locations by name, so I'm going to implement two new commands. REMEMBER(name) will remember the current location as “name" and RECALL(name) will return to that location.
Implementing this is not difficult. First I will add those commands to the Nearley parser:
# Remember a location rememberElement -> "REMEMBER"i WS "(" WS dqstring WS ")" WS {% data => ({op: "REMEMBER", name: data[4]}) %} # Recall a location recallElement -> "RECALL"i WS "(" WS dqstring WS ")" WS {% data => ({op: "RECALL", name: data[4]}) %}
If you remember your Nearley this is pretty straightforward.
Then I'll implement the two new operations in interpretCDL in compass.js:
const memory = {}; } else if (op.op == 'REMEMBER') {
memory[op.name] = radius; } else if (op.op == 'RECALL') { radius = memory[op.name]; }
memory is a Javascript dictionary that will keep track of the remembered locations. To REMEMBER a location, we set the name of the location in the dictionary to the current value of the radius. (Which is where we're drawing.) To RECALL a location, we get the remembered location out of the dictionary and set radius to that value.
With that in place, I can now modify the compass rules as so:
<twoLayerCompass> => REMEMBER("start") <bottomLayer> <topLayer>; <bottomLayer> => SPACE(`Utils.randIntRange(10,35)`) <ring> REMEMBER("insideEdge"); <interCardinalPoints> => RECALL("insideEdge") RPOINT(0.7854, 4, 0.85, 1, 1, "black", "white", "black"); <cardinalPoints> => RECALL("start") RPOINT(0, 4, 0.85, 1, 1, "black", "white", "black");
I have to remember and return to two locations. The first is the start location, so I can go back there to draw the cardinal (N/S/E/W) points. I also need to remember where the inside edge of the bottom layer is, because I want the intercardinal (NE/SE/SW/NW) points to just reach the inside edge.
And now even when the bottom layer ring is far out, or far in towards the center, the cardinal points still reach to the outside of the compass:
So now I can play around a bit and pick a range for this parameter. 10 to 30 seems to be reasonable to me, but you can make your own decision. This process of selecting independent random ranges for the parameters of the individual elements I called Level 1 procedural generation in a previous posting.
Now that I'm repeatedly generating compasses to check the range on parameters, I'm running into a problem that I noted in the Suggestions to Explore last time -- if you hit the Test button more than once, the new compass gets drawn on top of the old compass:
selectAll is a D3 function that lets us act on all the elements that match an expression. In this case, the wildcard '*' matches all the elements within the SVG element, and then the remove() method removes those elements. This has the effect of clearing the SVG before the new compass is drawn.function test(svg) { // Remove any previous compass svg.selectAll('*').remove(); const rules = prepareLodestone(compassRulesText); const cdl = executeRules('<compass>', rules, s => eval(s)); const result = interpretCDL(svg, parseCDL(cdl, true), [100,100], 75, true); };
Level 2 of procedural generation is multi-part constraints. There are some of these already built into this compass -- namely that the intercardinal points are constrained to start at the inner edge of the ring. That's certainly something we could experiment with.
<ring> => <thickThin> | <thinThick> | <thinThinThin> | <thinThickThin>; <thickThin> => <thickCircle> SPACE(3) <thinCircle>; <thinThick> => <thinCircle> SPACE(3) <thickCircle>; <thinThinThin> => <thinCircle> SPACE(3) <thinCircle> SPACE(3) <thinCircle>; <thinThickThin> => <thinCircle> SPACE(3) <thickCircle> SPACE(3) <thinCircle>;
When I added these rules I realized that I'd missed a Level 1 opportunity -- the space between the circles could be varied. I find this pretty common -- I'll work back and forth across the different levels of procedural generation, and making a change at one level will cause me to go back and add related changes at different levels.
With those rules in place I'm now generating a wider variety of compasses, although they're all still obviously in the same family:
I also think about whether or not I should simply accept this compass, even if I don't like it a lot. There's a trade-off between getting a wide variety of interesting results from procedural generation and accepting some poor results. If you try to “clamp down" too much to avoid unhappy results you end up with something that can generate only in a limited area of the creative space and that's usually pretty boring (if competent). So it might be better to accept some level of bad results, particularly if you can toss those out and just use the good results. On the other hand, this can be a trap if you're building something like Dragons Abound with many different procedural generation systems. If each system has only a 1% chance of getting a bad result, but you have 100 systems, then your chance of getting all 100 good results is only about 40% (!). (The power of combinatorics.) So you'll be throwing out a lot of bad results.
Let me finish off this compass by adding labels to the cardinal points. To do this I'll draw the labels first and then draw the compass inside the labels.
<twoLayerCompass> => <labels> REMEMBER("start") <bottomLayer> <topLayer>; <labels> => RTEXT(0, 4, "Serif", 16, "black", "", "bolder", "vertical", '["N", "E", "S", "W"]') SPACE(8);
(Note that I have to put the array of labels in single quotes. Otherwise Lodestone is going to interpret them as a weight -- Lodestone expects anything between square brackets to be a rule weight.)
The labels are an example of where we might get a Level 3 external constraint in procedural compass generation. Rather than always use the same font, or pick a font randomly, we might want to use a font that matches (or complements) the fonts we're using in the rest of the map. But for now I don't have that constraint, so I'll modify this to add some Level 1 variation in the font, size, and type of the labels.
I've added a couple of new font options here: Lobster and IM Fell English. These are not fonts that the browser knows about by default, so I need to add some code to the test.html web page to load these fonts. These are Google Fonts, meaning I can load them off of a Google server with this incantation that I've added near the top of test.html:<twoLayerCompass> => <labels> REMEMBER("start") <bottomLayer> <topLayer>; <$labelFont> => "Serif" | "Lobster" | "IM Fell English"; <$labelSize> => 14 | 16 | 18; <$labelStyle> => "normal" | "bold" | "bolder"; <labels> => RTEXT(0, 4, <$labelFont>, <$labelSize>, "black", "", <$labelStyle>, "vertical", '["N", "E", "S", "W"]') SPACE(8);
<link href='https://fonts.googleapis.com/css?family=Lobster' rel='stylesheet' type='text/css'> <link href='https://fonts.googleapis.com/css?family=IM+Fell+English' rel='stylesheet' type='text/css'>
(This is a partial answer to one of the Suggestions to Explore in Part 8.)
The complete rules for this compass now look like this:
<compass> => <twoLayerCompass>; <twoLayerCompass> => <labels> REMEMBER("start") <bottomLayer> <topLayer>; <$labelFont> => "Serif" | "Lobster" | "IM Fell English"; <$labelSize> => 14 | 16 | 18; <$labelStyle> => "normal" | "bold" | "bolder"; <labels> => RTEXT(0, 4, <$labelFont>, <$labelSize>, "black", "", <$labelStyle>, "vertical", '["N", "E", "S", "W"]') SPACE(8); <bottomLayer> => SPACE(`Utils.randIntRange(10,30)`) <ring> REMEMBER("insideEdge"); <ring> => <thickThin> | <thinThick> | <thinThinThin> | <thinThickThin>; <$ringSpacing> => 1 | 2 | 2 | 3 | 3 | 4; <thickThin> => <thickCircle> SPACE(<$ringSpacing>) <thinCircle>; <thinThick> => <thinCircle> SPACE(<$ringSpacing>) <thickCircle>; <thinThinThin> => <thinCircle> SPACE(<$ringSpacing>) <thinCircle> SPACE(<$ringSpacing>) <thinCircle>; <thinThickThin> => <thinCircle> SPACE(<$ringSpacing>) <thickCircle> SPACE(<$ringSpacing>) <thinCircle>; <$thickWidth> => 4 | 3.5 | 3; <$thinWidth> => 1.5 | 1 | 0.5; <thickCircle> => CIRCLE(<$thickWidth>, "black", "none"); <thinCircle> => CIRCLE(<$thinWidth>, "black", "none"); <topLayer> => <interCardinalPoints> <cardinalPoints>; <interCardinalPoints> => RECALL("insideEdge") SPACE(`Utils.randIntRange(-5,5)`) RPOINT(0.7854, 4, `Utils.randRange(0.80,0.925)`, 1, 1, "black", "white", "black"); <cardinalPoints> => RECALL("start") RPOINT(0, 4, `Utils.randRange(0.80,0.925)`, 1, 1, "black", "white", "black");
What's striking about this is that I already have 20 rules for generation, just for this one type of compass! Of course, some of these rules will likely be reused in other compass types, but in general I find that this sort of grammar-based procedural generation leads to many rules, and organizing and keeping track of them can sometimes be a challenge.
A reminder that if you want to follow along from home, you need to download the Part 14 branch from the Procedural Map Compasses repository on Github and get the test web page up and open the console. Part 1 has instructions, but the short version (on Windows) is to double-click mongoose-free-6.9.exe to start up a web server in the Part 14 directory, and then select the test.html link. You'll find the rules for the compass above in the compass.js file and you can experiment with changing and extending the rules. You can also try out this code on the web at https://dragonsabound-part14.netlify.app/test.html although you'll only be able to run the code, not modify it.
Suggestions to Explore
- Level 4 procedural generation is independent subtypes. A rule of this sort for the compass points would be to have wavy compass points for the intercardinal compass points. Implement this rule.
- There are many more subtypes to explore for the <ring> in this compass style. Implement the scale from the other example at the top of this posting. Implement some rings that use radial circle, triangle or diamond elements.
- Suppose you want to implement a meta-subtype for <ring> which would repeat the same ring twice:
In general, is there any way to write rules which will repeat some previous rules? If not, how would you add that capability?
No comments:
Post a Comment
Note: Only a member of this blog may post a comment.