Rocks'n'Diamonds

Hi everybody,
after quite a long struggle, I am proud to announce the RnD Documentation Draft.

The whole work has been checked by Holger during the redaction, but this last update contains something new even for him.

I hope that you will be so kind to help us by taking a look to:
http://www.zomis.net/rnd/info.php?f=612
and by pointing out any bug, incompleteness or mistyping that you can find.
There are quite some, I am pretty sure of it.

Among the incomplete things, I need some examples about the Personal Folders (as well about the Common Folder) applied to the Mac and Unix-like Systems.

By the way, I have just noticed that the whole documentation is broken in IE, while it's quite readable anyway in Opera. As usual, Firefox renders it as it should be rendered. I'll fix that later.

Have good time, thank you for your attention.

I just read parts of the documentation, and I've got some stuff...

FAQ
- Snapping and custom elements (snapping a CE can trigger a change page)
- Also mention that there's a Supaplex style of dynamite
- I'd say that dynamites are best placed at a 3 tile distance:


(Think about the player as where to put dynamite)
Or maybe that distance is actually called 2 tile distance? (Native-English speakers please?)

Read this sentence again:
"If you typed those keys correctly, you will see a new tape appearing in the Tape Recorder, otherwise, you will be warned by a "NO SOLUTION TAPE FOR THIS LEVEL" message."
- It says that if you type the keys correctly ..., otherwise... which means that if you type :ist incorrectly, you will be warned by a "No solution tape for this level". I think it should be changed to:
If you typed those keys correctly and a solution tape for the level exists, you will see a new tape appearing in the Tape Recorder. Otherwise, if no solution tape exists, you will be warned by a "NO SOLUTION TAPE FOR THIS LEVEL" message.

- Which port does RND in network mode use? (Could be a good think to know for firewall users)

Personal folder in Linux:
/home/user/.rocksndiamonds (or /root/.rocksndiamonds if you are logged on as root)

Elements Reference
Primary Tasks - On levels with Custom Element, a CE action could trigger the finish of a level. (Maybe write that "Final note" earlier in the document?)

Sokoban elements, Switchable Lamps and Penguins will be ignored and replaced with regular walls by the EM engine. Using the EM engine, any closed exit door will open up as soon as the emerald counter reaches zero.
- "Using the EM engine" could sound a little strange to newbies, maybe a link with a little more detail about the different game engines avalible to choose from the level editor?

There are two main kinds of wall: normal walls and steel walls. The first are called so because they can be destroyed by an explosion (either caused by a dynabomb, by another explosive or by smashing an enemy/creature), the second are completely indestructible.
- "the second" could - if you misread it - refer to "another explosive", I suggest writing "the steel walls" instead.

Can a plant really be considered as a "Creature"?

"The Mole can move both horizontally and vertically, moves straight until it reaches an obstacle and gets involved in chain-explosions."
- This could be misunderstood, it needs to get involved in chain-explosions to stop moving straight?

All the keys are destructible, they hold their positions without falling and they are not slippery. In order to pass through a door or a port, the field on the other side must be empty.
- I suggest making the world "pass" bold. And maybe adding the text that "Walking through a door does not need the field on the other side to be empty".
Or maybe write that when you can stand inside/on a door, you do not need empty space to walk out.

Colored Doors and Keys (RnD-style)
- The grayed doors are not displayed in the same order as the full-color doors (red, yellow, green, blue vs. green, yellow, red, blue)

"Falling rocks can change the position of these switches."
maybe should be written as:
"When rocks smash a switch, it changes the position of these switches."

Gravity Ports
- Gravity ports will be displayed as one-way ports during gameplay (with red color instead of blue)

Four-ways Port
"The entrance and the exit will be always on opposite sides." -->
"The entrance and the exit will always be on opposite sides."

Living Walls
"Cells appear/disappear every each half second."
Isn't it enough to write ONE of the words "every" and "each"?

"Quicksand with stone" is called "Quicksand with rock" in the RnD editor
There doesn't seem to be any stones in RnD.

Conveyor Belts
The graphic displaying the conveyor belts looks strange in Firefox, the middle is placed around 5 pixels higher than the other parts.

Incorrect href:
R&D%20User%27s%20Manual.html#NOTE_LOCALE_DEP

The "R&D User's Manual.html" file does not exist

Found in the manual.html file

Wow, thank you Zomis, you have spotted a lot of things. Nice suggestions also for what regards some sentences. I'll fix them as soon as possible, until then, I'll wait for other reports/suggestions.

By the way, I don't know which port RnD uses in Network mode...

Also, I am missing some examples about the Common folder on Unix. It is not strictly necessary, as it is the less used folder, but for love of completeness, it should be mentioned.

I am working on your report, Zomis.
I think that "2 tiles of distance" should be right: when two elements are side by side, they are at 0 tiles of distance from each other. In any case, I'll take on your "not mentioned" suggestion and I'll add a sketch to that paragraph.

WOW!
That's a lot of documentation stuff, well done, Francesco!

Maybe you should add a version number and a date.

What I don't like so far is the HTML layout:
- background colors not working in IE
- the background graphics are very ... distracting ...
- I would definitely prefer a better menue structure. You have to scroll, scroll and scroll to reach the menue at the top. Navigation should be improved and you should always see, where you are inside the documentation. I know it's difficult ... perhaps with frames or split the long files into several small ones ...
- what about a big graphic with all elements (like the Elements List Area in the editor) at the top of the element reference for fast access to a specific element?

Some additional comments:
1.

The Acid destroys anything falling into it, players included.

... falling or moving into it ...

2. The center graphics of the conveyor belts are displaced some pixels upwards, is that intended?

3. The example Working Folder should be the one proposed by the auto-installer (C:\Program Files\Rocks'n'Diamonds ?).

4. Besides folder information about XP, Unix and Macintosh we should also add Vista ...

5. Typo in "Steel Walls":

... although other elements than can fall down ...

... that ...

6. "Plant" is deadly-to-collide-with instead of deadly-to-touch, isn't it?

7. What about detailed information about gravity? But don't know where to put it ...

8. CE and GE should be added to the Elements Reference. With a short description that CEs can look like any other element and have strange behaviour and GEs can randomly place elements in the level. And of course with an URL to "Custom Elements Programming".

9. Conveyor Belts: I don't like the phrases like

These switches can be changed of position by falling rocks.

or

... inactive position ...

. What about replacing "position" with "status"?

Common directory in Unix is /usr/share/games/rocksndiamonds in most cases. Sometimes, if the program was compiled by hand and not installed by standard installers, it may be /usr/local/share/games/rocksndiamonds. I'm not sure if the latter is common enough to be mentioned.
(What's your opinion, Holger?)

BTW a big and ultimate NO for frames. Maybe a position:fixed block could be used, but splitting the file into smaller ones IMHO also increases readability and usability of the documentation, so I'd prefer that.

I thank you all for your help. I am taking note of all of your fixes, suggestions and additions, and I will go on watching this thread while fixing the whole work.

Stay in touch

Tomi wrote:[...] splitting the file into smaller ones IMHO also increases readability and usability of the documentation, so I'd prefer that.

The only problem with that is that it would be nice to just have one file if you wanted to store it somewhere on your system.

Daniel H. wrote:

Tomi wrote:[...] splitting the file into smaller ones IMHO also increases readability and usability of the documentation, so I'd prefer that.

The only problem with that is that it would be nice to just have one file if you wanted to store it somewhere on your system.

You'd need tons of other files anyway for the graphics of the elements.

Francesco: Just doing my best Haven't read the complete manual and level editing stuff though...

Maybe a "Top" href could be used on every part to navigate to the top? It's a well-used system even though I myself don't like it very much (I prefer grabbing the scroll to the right and move it with the mouse, or simply pressing the "Home" button... or holding "Page up")

What I don't like so far is the HTML layout:
- background colors not working in IE
- the background graphics are very ... distracting ...
- I would definitely prefer a better menue structure. You have to scroll, scroll and scroll to reach the menue at the top. Navigation should be improved and you should always see, where you are inside the documentation. I know it's difficult ... perhaps with frames or split the long files into several small ones ...

It's a bad behaviour to criticize something without proposing an alternative solution, so here it is:
reference.html (TABLE-Version 1.0.4)

It's far away from a final solution, it just shows some basic ideas.
It uses two tables (divs should be better), one for the Index area and one for the text area (in the hurry I only added the text for 1.2 Introduction, 1.3 Primary Tasks and 1.4 Rocks ...).

Improvements (in my opinion):
- no distracting background (the background fixed yamyams drove me crazy ...)
- no fixed width
- keeping the "list style" (like Francesco's Index) for the text area to help keeping track
- clicking on a text area URL leads to the corresponding point in the Index
- clicking on a coloured area leads to the corresponding point in the Index (requires Javascript enabled for non-IE browsers). Unfortunately this is not so intuitive as I thought before ... Ok, so what about captions like this in the text area:
[url=http://#]Elements Reference[/url] -> [url=http://#]Primary Tasks[/url] -> Collect a certain amount of Emeralds

Ideas:
- what about removing the text area and putting all the text inside the Index area into invisible divs and make them visible/invisible by clicking the corresponding menu url? But that would definitely require Javascript enabled ...

Ideas:
- what about removing the text area and putting all the text inside the Index area into invisible divs and make them visible/invisible by clicking the corresponding menu url? But that would definitely require Javascript enabled ...

Ok, here it is :
docs.html (DIV-Version 1.0.1)

Please enable Javascript. Should work with IE and Firefox.

Navigation is really fast, you can hide all lower DIVs by clicking an upper one (in empty area). I like it ...

Dynamically showing divs is not a good idea IMHO. You may use it but not turned on as default. (And provide a fallback for people with JavaScript disabled.) I think it would be distracting and hard to use. Also, the rest of the web doesn't do it and most users don't like having to "learn to use a site/page". (Including me.)

As for the index: I also don't like how the pages are divided into "index" area and "content" area. What about the MediaWiki index style? (Wikipedia and MDC use it, example http://developer.mozilla.org/en/docs/A_ ... JavaScript ) I think it's nicely done. (But you still have to scroll the page. Stay with "back to top" links.)

And BTW, this of course is not meant as criticism, but as suggestions. The documentation itself is great!

One more thing: AFAIK a lot of good articles on usability was published on ALA: http://www.alistapart.com/topics/userscience/usability/

Maybe this thread should be split into content and layout discussion ...

Dynamically showing divs is not a good idea IMHO. You may use it but not turned on as default. (And provide a fallback for people with JavaScript disabled.)

There is already a fallback: for people with Javascript disabled: all DIVs will be visible. Of course, then you have to scroll a lot, but that's the same in Francesco's version ...

I think it would be distracting and hard to use.

Have you even tried it? I agree that the TABLE-version is a little bit confusing, but the DIV-version? The mechanism is like a folder tree in Windows Explorer. I'm really curious if it's intuitive, so maybe some more people can give feedback?

Also, the rest of the web doesn't do it ...

Sure? I often see it (at least in a more basic way: question and visible/invisible answer) and I like it, because it's easy and fast to use, e.g. http://www.microsoft.com/windows/window ... ation.mspx

As for the index: I also don't like how the pages are divided into "index" area and "content" area. What about the MediaWiki index style? (Wikipedia and MDC use it, example http://developer.mozilla.org/en/docs/A_ ... JavaScript ) I think it's nicely done. (But you still have to scroll the page. Stay with "back to top" links.)

There it is again: you can dynamically show and hide the menue!
And you already mentioned why I don't like this MediaWiki example: scroll, scroll, scroll and no "back to top" links.

And BTW, this of course is not meant as criticism, but as suggestions. The documentation itself is great!

Full acknowledge! The documentation is already very good, Francesco did a great job. But therefore it would be a shame, if it would be too complicate or too laboriously to use ...

Here is the online version of the (updated) documentation:
http://spazioinwind.libero.it/entuland/rnd_doc

You will see several changes. Sorry if I don't report here all the changes. Most of the suggestions/fixes that you have posted above have been taken in charge. I could have missed something, but I'll check it as soon as possible.

The Common Folder example you have posted above is right? I mean, isn't that a "Working" folder? Seems strange that there is no dot, no single quote and no uppercase in that "rocksndiamonds" folder...

In the Docs I am distinguishing between "Personal", "Common" and "Working" folders, hope you agree with this naming method.

Also, I still miss the port used by RnD in network mode.

Check out the Update Log on each page to see the changes/additions.

The whole updated package is available from the same old location:
http://www.zomis.net/rnd/download.php?id=612

@Zomis: the FA still ignores description changes. Would you please change it manually to "Updated documentation package, release candidate nr. 2"?
That would be very kind of you.