doc: add component and ui element docs #102

jdrueckert · 2023-04-22T22:23:45Z

Player Docs - UI elements and game mechanics

Health HUD
Damage Overlay
Directional Damage Overlay

Modder Docs - concepts & public API

Health
Damage
Regeneration
Restoration

Developer Docs - architecture & API

API (master) Reference
Snapshot API (develop) Reference

jdrueckert · 2023-04-23T09:18:10Z

Had some more discussion with @skaldarnar on module doc structure today, so I'll add some more changes before setting this back to "Ready for review".
Gist:

player documentation on UI elements, effects and mechanisms introduced by activating this module
modder documentation on public API (which events are processed and sent by module systems, which components can be used by module-external systems) based on common use cases
developer documentation on module architecture + link to javadoc

skaldarnar

Added a few smaller remarks and minor notes, but overall looks good and improves the documentation! 👍

skaldarnar · 2023-04-25T06:50:39Z

docs/damage.md

+Self-inflicted causes include, for instance, falling, drowning, or poison damage.
+Damage inflicted by a third party typically involves some form of hitting the affected entity.


I'm not sure about this separation 🤔 I wouldn't have thought of "poison damage" as self-inflicted, for example.

Why do we think this distinction is important?

Ideally, the instigator (I guess this is what this is technically about) could carry information about the body of water the player drowned in, the exact poison or disease they are infected with, etc. The instigator might not be another player or NPC, but it could be any entity in the game.

I do vaguely recall this from the past - poison is "internal" damage in a sense, unlike third party direct damage. Probably "self-inflicted" is a poor term for that. It would be nice if an internal damage effect had an original trigger source that could be referenced as well.

Player X died from poisoning, after getting too close to a Thornwood Cactus!

That might be a bit of a lofty goal for this point in time tho :-)

Why do we think this distinction is important?

This distinction is important because the directional damage indicator depends on having a direction to indicate. If we as the player are drowning in water, suffocating due to gas, or dying to poison in our system, there is no specific direction for the damage indicator to indicate as the "instigator" is in ourselves (poison) or all around us (water/gas).
We can also make the distinction between an instigator in or all around us vs an instigator at a specific location, however I have even less of a clue how to name that then...

Probably "self-inflicted" is a poor term for that.

Yeah, naming things is not exactly a strength of mine... I'm happy about any suggestions!

It would be nice if an internal damage effect had an original trigger source that could be referenced as well.

In terms of the directional damage indicator, I'm not sure how it would help the player to know that the cactus they originally got poisoned by, for instance is somewhere to their right...

For the player the interesting point is "why / where from do I lose health right now?" The directional damage indicator shows them, where their attacker can be found, for instance an archer. It's important for the player to understand whether there's an attacker they might be able to defend themselves against or whether the damage is caused by an "environmental" (again maybe not the right term) effect like water, gas, poison, ...

skaldarnar · 2023-04-25T06:51:22Z

docs/damage.md

+The `DamageSystem` handles damage dealt to entities with health.
+The `BlockDamageAuthoritySystem` enables blocks to sustain some damage before getting destroyed.
+The `DamageEffectAuthoritySystem` produces block particle effect in the event of damage.


This will be rendered as single paragraph. Should we use bullet points here?

skaldarnar · 2023-04-25T06:51:57Z

docs/damage.md

+Send a `DoDamageEvent` to a specific entity to deal damage to it.
+
+Use the `DamageResistComponent` to configure an entity to not take damage from specific damage types.
+Examples for damage types are drowning (`engine:drowningDamage`) or explosive (`engine:explosiveDamage`) damage.


Future: explain how to add more damage types?

I have a vague recollection that we have a module that adds a new damage type. But I have no idea what that is 🤔

Created #103 to track this. Not sure we want the main docs for that in the Health module, though... I guess it makes more sense putting it in the engine wiki and linking to it from docs of relevant modules including Health.

skaldarnar · 2023-04-25T06:53:00Z

docs/damage.md

+Event chain:
+* `DoDamageEvent`
+* `BeforeDamageEvent`
+* Entity damaged, health component saved


What do you think of using italic font to indicate that this is an abstract explanation of what is happening?

Suggested change

* Entity damaged, health component saved

* _Entity damaged, health component saved_

skaldarnar · 2023-04-25T06:53:25Z

docs/damage.md

+* `OnDamagedEvent`
+
+Commands:
+* `damageResist(damagetype,percentage)`: gives resistance to damage (damagetype = all for total resistance).


Future: Would be nice to have a command to list possible damage types.

Great idea, I can write an issue for that. However, I'm wondering whether that should be a command introduced by Health... Damage types are an engine-level concept after all...

I like to challenge that damage types are part of the engine if the engine itself does not have a notion of, well, health....

docs/health.md

skaldarnar · 2023-04-25T06:56:07Z

docs/regeneration.md

Future: Link to JavaDoc when referencing events or methods.

Created #104 to track this. This is currently blocked by #101

docs/ui-damage-overlay.md

Co-authored-by: Tobias Nett <[email protected]>

doc: add component docs

648b85d

jdrueckert added Type: Improvement Request for or addition/enhancement of a feature Category: Doc Requests, Issues and Changes targeting javadoc and module documentation labels Apr 22, 2023

jdrueckert requested a review from skaldarnar April 22, 2023 22:23

doc: add ui docs with screenshots

be07851

jdrueckert changed the title ~~doc: add component docs~~ doc: add component and ui element docs Apr 22, 2023

jdrueckert marked this pull request as draft April 23, 2023 09:17

doc: restructure Health module docs

6ab559f

jdrueckert marked this pull request as ready for review April 24, 2023 20:29

skaldarnar previously approved these changes Apr 25, 2023

View reviewed changes

jdrueckert dismissed skaldarnar’s stale review via 07fe027 April 30, 2023 13:01

jdrueckert and others added 2 commits April 30, 2023 15:01

doc(damage): integrate review comments

07fe027

doc(health): integrate review comment

ce8a155

Co-authored-by: Tobias Nett <[email protected]>

jdrueckert requested review from skaldarnar and Cervator June 30, 2023 20:09

skaldarnar previously approved these changes Jun 30, 2023

View reviewed changes

chore: integrate suggestion

1249333

Co-authored-by: Tobias Nett <[email protected]>

jdrueckert dismissed skaldarnar’s stale review via 1249333 June 30, 2023 20:49

skaldarnar approved these changes Jun 30, 2023

View reviewed changes

jdrueckert merged commit 335d6d7 into develop Jun 30, 2023

jdrueckert deleted the doc/components branch June 30, 2023 20:58

skaldarnar mentioned this pull request Aug 7, 2023

Roadmap for moving Iota modules to the engine repo MovingBlocks/Terasology#5129

Closed

3 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

doc: add component and ui element docs #102

doc: add component and ui element docs #102

jdrueckert commented Apr 22, 2023 •

edited

Loading

jdrueckert commented Apr 23, 2023 •

edited

Loading

skaldarnar left a comment

skaldarnar Apr 25, 2023

Cervator Apr 26, 2023

jdrueckert Apr 30, 2023

skaldarnar Apr 25, 2023

jdrueckert Apr 30, 2023

skaldarnar Apr 25, 2023

Cervator Apr 26, 2023

jdrueckert Apr 30, 2023

skaldarnar Apr 25, 2023

jdrueckert Apr 30, 2023

skaldarnar Apr 25, 2023

jdrueckert Apr 30, 2023

skaldarnar Jun 30, 2023

jdrueckert Jun 30, 2023

skaldarnar Apr 25, 2023

jdrueckert Apr 30, 2023

		Self-inflicted causes include, for instance, falling, drowning, or poison damage.
		Damage inflicted by a third party typically involves some form of hitting the affected entity.

	* Entity damaged, health component saved
	* _Entity damaged, health component saved_

doc: add component and ui element docs #102

doc: add component and ui element docs #102

Conversation

jdrueckert commented Apr 22, 2023 • edited Loading

jdrueckert commented Apr 23, 2023 • edited Loading

skaldarnar left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jdrueckert commented Apr 22, 2023 •

edited

Loading

jdrueckert commented Apr 23, 2023 •

edited

Loading