Clarify the game rules

[dmytroshytikov]

This file is a much better place for all this information.

[Mikolaj]

Thank you! Is the an alternative to #122 or an update version of the old PR? In the latter case, I guess it would have been easier for you to force-push (push -f) an amended commit (git commit -amend -a) to the old PR instead. But no harm done, of course.

[Mikolaj]

BTW, have a look at the CI -- it yelled at you. :D

[dmytroshytikov]

BTW, have a look at the CI -- it yelled at you. :D

So far, can't see. I will see if I can observe the issue again.

[Mikolaj]

I mean, the "Some checks were not successful" reports problems. I think they are about exceeding 80 characters.

[Mikolaj]

The "Some checks were not successful" is CI.

[Mikolaj]

"Continuous integration" -- compiling, checking and testing after each push.

[dmytroshytikov]

I mean, the "Some checks were not successful" reports problems. I think they are about exceeding 80 characters.

Yeah, I see.
Well, I thought that as it is a text file (the markdown type), I can just type in the text I wanted, and the machine will automatically resize it as it should be. What should I do with it?
And when I went to the file, I can see changes I suggested there.

[Mikolaj]

Markdown is a double purpose format. Some people view it formatted:

https://github.com/AllureOfTheStars/Allure/blob/b0c0ffad460100aadf4d5ba3271ec4f9b1c1f68f/GameDefinition/PLAYING.md

other view it raw, e.g, in the console with a cat or less command

https://github.com/raw/AllureOfTheStars/Allure/b0c0ffad460100aadf4d5ba3271ec4f9b1c1f68f/GameDefinition/PLAYING.md

Additionally, the latter form is used in the game itself. The help screen ends with this file included (as captured at compilation time), in raw form, and the start menu displays the initial portion, slightly formatted.

I'm afraid, to keep the 80 columns, one needs to use an old fashioned text editor with monospace font and a ruler or window size set to 80 columns. Then commit the changes using a commandline git. Alternatively, perhaps Visual Studio can do that, but I'm not familiar with it.

[dmytroshytikov]

Markdown is a double purpose format. Some people view it formatted:

https://github.com/AllureOfTheStars/Allure/blob/b0c0ffad460100aadf4d5ba3271ec4f9b1c1f68f/GameDefinition/PLAYING.md

other view it raw, e.g, in the console with a cat or less command

https://github.com/raw/AllureOfTheStars/Allure/b0c0ffad460100aadf4d5ba3271ec4f9b1c1f68f/GameDefinition/PLAYING.md

Additionally, the latter form is used in the game itself. The help screen ends with this file included (as captured at compilation time), in raw form, and the start menu displays the initial portion, slightly formatted.

I'm afraid, to keep the 80 columns, one needs to use an old fashioned text editor with monospace font and a ruler or window size set to 80 columns. Then commit the changes using a commandline git. Alternatively, perhaps Visual Studio can do that, but I'm not familiar with it.

So, do I need to resize my inserts?
I can do that, I just thought it will be done automatically. But I can think how to rearrange it. It is an interesting coding task :)
Do I understand correct that I need to make the text as 80 symbols per raw and with spaces before the first letter of each raw, right?

[Mikolaj]

So, do I need to resize my inserts?
I can do that, I just thought it will be done automatically. But I can think how to rearrange it. It is an interesting coding task :)

I'm afraid that's necessary and I'm afraid it can't be done automatically (not perfectly at least and not without ML), because you don't want to split phrases that go together, such as "to " or "".

Do I understand correct that I need to make the text as 80 symbols per raw and with spaces before the first letter of each raw, right?

The special spaces are only needed for the first paragraphs, the ones that go into the starting menu. The rest just needs the rows to be below 80 character long and, say, above 55.

[dmytroshytikov]

I'm afraid that's necessary and I'm afraid it can't be done automatically (not perfectly at least and not without ML), because you don't want to split phrases that go together, such as "to " or "".

I'll see how to deal with this issue.

The special spaces are only needed for the first paragraphs, the ones that go into the starting menu. The rest just needs the rows to be below 80 character long and, say, above 55.

So, there is no need to have space in each raw, right? Just below 80 characters per raw, right?

[Mikolaj]

So, there is no need to have space in each raw, right? Just below 80 characters per raw, right?

Yes. But if in doubt, please look at the surrounding text. There are no leading spaces. Why do you expect them to be there? Is this the misleading github display? (BTW, it's "row".)

[dmytroshytikov]

So, there is no need to have space in each raw, right? Just below 80 characters per raw, right?

Yes. But if in doubt, please look at the surrounding text. There are no leading spaces. Why do you expect them to be there? Is this the misleading github display? (BTW, it's "row".)

Pardon me. The first part of the file has leading spaces.
Ok, I'll rearrange.

[dmytroshytikov]

Does this output work?

[Mikolaj]

Let's see what CI says. ;)

[dmytroshytikov]

Interesting, why it takes so much time now.

[Mikolaj]

It probably doesn't fail at once, so probably it's fine now.

[dmytroshytikov]

What do these command lines do? Do they process this text file in different ways?

[Mikolaj]

Which lines, precisely?

[dmytroshytikov]

These checks

[Mikolaj]

To make sure we talk about the same thing: could you click on such a check you have in mind and copy here the link you followed and a fragment of the text you mean?

[dmytroshytikov]

I know it is a strange question :)

[Mikolaj]

The question is fine. It's just imprecise. I would never guess the "command lines" you mention are these CI job descriptions. Each line represents a single CI job that runs in the cloud. Did you try clicking on the link for any of the jobs? I think it would answer your question and it would not merge the PR, no worry. :) It says "Details", not "Merge".

[Mikolaj]

Well done. Such technical texts require a lot of work to get all the details right and also to condense and also to deduplicate and harmonize with the rest of the document, so this is going to take a lot of effort still.

[Mikolaj]

Later on we write "Weapon damage and other item properties are displayed using the dice notation xdy, which denotes x rolls of y-sided dice." Shall we standardize the notation? Either ~d~ in both places or xyd in both places? Or is this fine?

BTW, you can use "View file" from the right hand ... menu to see how the file is rendered in markdown. You'd notice that ~ without back quotes causes a text to be stroked through.

[dmytroshytikov]

I forgot the notation. I will change. BTW:

1. is it reasonable to write xdy + z%? Most of weapons is xd1. That means there are no dice.
2. z% - does it mean the bonus to this weapon? For example, ceramic splinter cells are 1d1 - 80%. Does it mean I need to fling 5 cells to inflict one point of damage? And does a spade 8d1 -- 10% inflict 7.2 points of damage?

[Mikolaj]

is it reasonable to write xdy + z%?

Yes, I think so. Currently, z only appears in damage dice and then it's just percent of the rolled value added on top of it, as described in "The dice of the first recharged weapon, the one that is going to be used now, is adorned with percentage damage bonus collected from the whole equipment of the pointman". This is not well enough explained anywhere, so it makes sense to elaborate on that.

Most of weapons is xd1. That means there are no dice.

Correct. Perhaps even all weapons. However, the engine supports weapons with non-trivial die, and also this resembles the common D&D and RPG notation, but underscores that there is no randomness, unlike in most other games.

z% - does it mean the bonus to this weapon?

Yes, It affects the item it's written about. When displayed in item menu, it's only the percentage contributed by the weapon (or whatever the item is). But on HUD, it's the sum total that affects the weapon, summed from all equipment.

For example, ceramic splinter cells are 1d1 - 80%. Does it mean I need to fling 5 cells to inflict one point of damage?

Yes. Thrown damage doesn't get bonuses from other equipment, so it will always be 80% for these splinters.

And does a spade 8d1 -- 10% inflict 7.2 points of damage?

That's melee, but so if you wear nothing else, then 7.2, but if not, it can be different. The HUD displays that total. This is described somewhere, but without much detail, so worth discussion from a different angle and with different words.

[Mikolaj]

I mean, the sums of bonuses are on HUD, but also in the # menu, as you correctly mention in the text.

[dmytroshytikov]

Another question:
A short club has 2d1 damage. But when the character equips it, it gives 2d1**+2** without percents. Does it mean that its damage was added to the character's natural one (I guess inflicted by the fists)?

[Mikolaj]

No, it's about different kinds of damage. That must be described in the manual. Could you have a look? If it's not easy to find, we have to make it so.

[Mikolaj]

BTW, that's also a key to an effective tank build, but the player is supposed to discover that by himself (as opposed to discovering UI meaning, which should be 100% clear and explicit from the docs).

[dmytroshytikov]

Hm. So far, I have not found anything similar in the "Battling monsters" section. I'll look at it again later.

[dmytroshytikov]

Integration did not work due to the symbol per line limit. Now, it must work.

[dmytroshytikov]

Just one more comment about the TAB command.

[dmytroshytikov]

I removed the TAB sentence (line 603-604). The rest seems to be fine.

[Mikolaj]

Really close now. Well condensed.

[Mikolaj]

I'd drop "Some", because all can be found in this way.

Perhaps it's worth it to preserve a couple of details from this removed text? E.g, here mention that "the lore menu, terrain submenu" shows the recipes for encountered terrain.

[Edit: I was being unclear. The removed text is the following:]

Stand adjacent to the workshop terrain (blue colon on the map) and experiment. Note that walkable positions can't be activated by bumping and, anyway, crafting requires the Modify command (key M) even for terrain that could be bumped into. Other crafting spots (e.g., any water and fire) work similarly, but the recipes differ. Read the recipes in the lore menu, terrain submenu, or by pressing ~ when crosshair points at terrain that enables crafting.

[dmytroshytikov]

Well, I wanted to emphasize that some recipes (for example, I guess, that secret armor you talked before) is not described in the lore menu.
I am somewhat unclear of what to add in lines 608-618.

[Mikolaj]

I meant the (repaired) spacesuit. I've just checked, it's there among the recipes of the bench of crafting (the workshop). I do think no are secret in the sense that the recipe is not visible to the user. However, some are hard to craft and until you craft the first specimen, the item does not show in the item lore, so its properties are secret.

[Mikolaj]

Regarding line the whole crafting subsection, I just wondered aloud whether some of the old text would be useful, since not all is already contained in the new text.

[dmytroshytikov]

I have added the suggested changes except for lines 608-618. I am unclear of what to do there.

[dmytroshytikov]

I have reshaped the crafting section slightly.

[dmytroshytikov]

reshaping again

[dmytroshytikov]

Reshape. Something blocks merging

[dmytroshytikov]

reshape

[dmytroshytikov]

Reshaping lines 611 and 612

[dmytroshytikov]

Remove whitespaces from the ends of all of the lines 542-613

[Mikolaj]

LGTM

Thank you!

[dmytroshytikov]

Yay! Finished!

[Mikolaj]

Well done. Your new version of the manual is now the one shown by the main manual hyperlinks. Only the in-game manual is the old one until a new release is made (which may take a while).