So what are CE values and what are "reference elements" (which can be found in the "REF" section of the level editor's element palette)?Also...has there ever been a finished instruction manual posted (since I have been away from the forum for awhile) that makes a simple explanation of using CE values and other things like the ref section of the game editor?
CE value and CE score
The CE score
Well, CE score is a value that can be configured when selecting a custom element (also called "CE" here), pressing the "Properties" button and then selecting the "Config 1" tab on the left: The default value for each CE is "10", just like for many other game elements (which are not custom elements). When setting the CE to "collectible", this value is added to the score when collecting this CE in the game. The CE score is unique for each custom element, but not for each instance of a custom element. What does this mean?
Well, if you have "custom element 1" (graphically displayed as some sort of wall with a "001" on it) with CE score "10", and place three of these elements in the level playfield, they will all have the same CE score of "10". That's no big surprise. But what happens if you set that CE to "can fall" and add a change condition (on the "Change" tab) to set the CE score to "100" after/when "impact (on something)"? The CE score will change to "100" instead of "10" if you let one of those three CEs fall down a few tiles. Collecting any (or all) of these three CEs will then increase the score by 100, not only when collecting the one CE that fell down. Changing the CE score will change it for all CEs of that kind (that is, with the same number, which is "001" in this example).
The CE value
With CE values, things are a bit different: Each of several instances of the same CE in the game has its own, unique CE value. Using the same example as above, but with CE value instead of CE score, will only change the CE value for those CEs that fall down, but keep the CE value of all other (same) CEs untouched. (However, collecting them won't add the CE value to the game score, as it is not treated as a "score" value, but this could be added with some additional CE conditions if required.)
Conclusion: Use "CE score" if you want to store values for all CEs of the same kind, and use "CE value" if you want to store values for each individual instance of a CE on the playfield.
And as a side note: You can not only store numbers as CE scores or CE values, but also (the internal numbers of) game elements, which you can then use later to re-create game elements from. Just use CE action "Set CE value" or "Set CE score" with action operator "=" and an action parameter under "[element]" (like "target", "trigger" or "action ->", with the latter specifying an explicit game element, while "target" and "trigger" are related to the "target element" or the "trigger element" used on that CE change page).
The "CE value" and "CE score" fields can be used for complex and tricky "CE programming", but within this post, only a few simple uses will be demonstrated.
Reference Elements
"Reference elements" are those elements that are listed in the "REF" section of the editor's element palette, and they can be used to refer to other game elements when creating CE changes.
The demo level set attached to this post will demonstrate most of them, and each level has an envelope with a short description of the reference element shown in that level. Here are some additional descriptions of these demo levels:
Level 1: Reference element "Element triggering change"
This level has a custom element with a rock, an emerald and a diamond above it. Any element that falls onto this CE triggers a change of that CE to a 3x3 block of this element. This is done by simply using the reference element with the name "Element triggering change" in the CE's change page that refers to the element that was causing (triggering) the CE change. More precisely, this reference element is used in the "extended change target" of that CE's change page to create not only a single new game element instead of that CE, but a whole 3x3 block (with 9 new game elements) at the previous CE's position (but requiring playfield tiles to be empty to create the new game element at the 3x3 block's playfield positions).
Level 2: Reference element "Player triggering change"
The second demo level nearly does the same, but not with game elements falling on a CE, but players touching a certain other (non-CE) game element. The CE in this level is then triggered by any player touching that other game element (the one with a traffic sign on it) and, as a result, changes to itself plus the player that has touched that other game element.
So we effectively used two reference elements here (in the "extended change target" area of the change page of this CE): The "self" reference element (named "the current custom element"), which just replicated the same custom element again, and the "player triggering change" reference element, which is used to add the player that triggered the change (therefore effectively teleporting that player to the new playfield position).
All this could indeed have been done without any reference element: Instead of the "self" reference element, the "custom element 1" could have been used. And instead of using the "player triggering change" reference element, four separate change pages could have been used, with player 1 to 4 who touched the other game element, and player 1 to 4 who will be created in the corresponding extended change target area. So, using reference elements just makes things a lot easier here.
Level 3: Reference element "CE value of element triggering change"
This level has two different custom elements: One ("001") that can "consume" things that fall on it (gems in this case), where "consume" means "remove that game element and store its element number in the CE value of this CE". The other CE ("002") can "produce" things, where "produce" means that a game element that falls on it will be removed, and its CE value will be taken as the element number of a game element that will be created three times at the bottom of the producing CE (which obviously only works with custom elements). To do this, the reference element "CE value of element triggering change" is used in the extended change target, to use the CE value of the CE that was falling onto it.
That way, all three different gems can be "stored" in the CEs below them (by just letting them fall onto them), which can then be pushed to fall onto CE "002", which re-creates those gems again. Especially, this shows clearly that each CE has its own, individual CE value.
Level 4: Reference element "CE score of element triggering change"
This level looks just like the previous level, and indeed they are nearly identical -- with one difference: Instead of the CE value, the CE score is used here. The CE score is not a value that individually exists for each CE on the playfield, but is the same for all same CEs (with the same number). Therefore, only one value can be stored for all three CEs of type "001" in this level. Which means that the last gem that was falling on any CE "001" is stored for all those CEs. Pushing those CEs onto CE "002" therefore always produces the same gem.
Level 5: Reference element "CE value of current element"
In this level, the CE that "consumes" the gems is the same as the one that "produces" them. Again, it stores the falling gem's element number in its CE value and produces that gem again if a rock falls onto it. To make this happen, it uses the reference element "CE value of current element" in this case, because it has to access its own CE value (and not the one of another CE that was triggering the change).
There is another custom element configuration setting required to make this work: On tab "Config 1", the checkbox for "use last CE value after change" has to be checked. This is needed to keep the CE value when the CE changes -- without this setting, the CE would re-initialize its CE value after each change, and would therefore "forget" the game element stored in its CE value.
Level 6: Reference element "CE x positions earlier or later in list"
These special reference elements just refer to those CEs that have a game element number that is by X lower (earlier in the list of CEs) or higher (later in the list of CEs) that the current CE (with "X" being in the range of "-8, ..., -1, +1, ..., +8"). So you can reference up to eight CEs earlier or later than the current CEs position in the element list.
What is this good for? Look at the level: There are four different keys and four different closed (unwalkable) doors, which can be changed to four different open (walkable) doors when collecting the key with the same color.
Creating all four keys and doors (which are 12 CEs overall) would be boring and error prone, as all four keys and doors are technically identical. Instead, just create a single key (one CE) and a single door (two CEs), but do not refer to the corresponding key CE directly when creating the change page (to let the door change from "closed" to "open" when collecting the key), but use a reference element that points to the matching relative CE position for the key CE (which is "-4" in this case) and for the second door CE in "open" state (which is "+4" in this case). (For the key, the setting "CE count" on tab "Config 1" was set to 0 to not let the key count like an emerald when collecting it.)
When done, just copy all three CEs three times, making sure that the new CEs have the same distance in the list of CEs as the old ones. When done, you have the final set of four keys and eight door CEs, which you can decorate now to give them different colors (by either using custom graphics or the CE setting "use graphics of element" on tab "Config 1", which was used in this level). That way, creating several similar, interacting CEs is much faster than editing them all manually, and you cannot accidently forget some setting or checkbox here and there.
You can download the whole demo level set below, together with all solution tapes.
