Mirrorlandia_minetest/mtimer
1
0
Fork 0
mirror of https://gitlab.com/4w/mtimer.git synced 2024-11-28 02:03:46 +01:00
Code Issues Projects Releases Wiki Activity

work on user-facing documentation

Browse Source 
addresses https://gitlab.com/4w/mtimer/-/issues/19
This commit is contained in:
Dirk Sohler 2021-10-09 05:46:15 +02:00
parent 7e367a7509
commit 16119cf22c
No known key found for this signature in database
GPG Key ID: B9751241BD7D4E1A
1 changed files with 26 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

42
README.md
View File

@ -12,45 +12,45 @@ The mod is game-agnostic and does not have any dependencies. The mod only interf
## Configuration
The timer display and settings are entirely configured on a per-player basis via configuration formspecs. Configurations are set when leaving the formspec via the buttons or when pressing enter or clicking the apply button (where available). Pressing the escape key cancels the changes.
The timer display and settings are entirely configured on a per-player basis via configuration dialogs. Configurations are set when leaving the dialog via the buttons or when pressing enter or clicking the apply button (where available). Pressing the escape key cancels the changes.
For opening the main menu simply enter the `/mtimer` chat command. From the main menu all configuration formspecs are accessible.
For opening the main menu simply enter the `/mtimer` chat command. From the main menu all configuration dialogs are accessible.
![Main Menu](screenshots/main_menu.png)
Simply click the button of the option you want to configure.
Configuration formspecs can be accessed directly by providing the respective parameter to the `/mtimer` chat command. Run `/mtimer help` to see a list of available parameters. You might need to bring up the console (F10 by default) to see all available parameters because the chat display might be too small.
Configuration dialogs can be accessed directly by providing the respective parameter to the `/mtimer` chat command. Run `/mtimer help` to see a list of available parameters. You might need to bring up the console (F10 by default) to see all available parameters because the chat display might be too small.
### Variables
Some formspecs allow you to use variables. The variables and their current (i.e. the moment when opening the formspec) values are shown below the input field.
Some dialogs allow you to use variables. The variables and their current (i.e. the moment when opening the dialog) values are shown below the input field.
![Real-World Time Format](screenshots/real_world_time_format.png)
Simply use the variables as shown. For example, to use the day name in the formspec shown above simply enter `{dname}`. Using unknown variables is possible. Those variables are rendered literal. So Entering `{foobar}` renders to “{foobar}” in the output.
Simply use the variables as shown. For example, to use the day name in the dialog shown above simply enter `{dname}`. Using unknown variables is possible. Those variables are rendered literally. So Entering `{foobar}` renders to “{foobar}” in the output.
Using a string being a variable is not possible (`{foobar}` will always render to it’s value if it is a valid variable). Using the same variable multiple times is possible.
Using a string being a variable is not possible (`{foobar}` will always render to it’s value if it is a valid variable) but using the same variable multiple times is possible.
### Confirmations
Pressing enter in an input field applies the changes. Not all formspecs have input fields. Sometimes there only schemes or just buttons.
Pressing enter in an input field applies the changes. Not all dialogs have input fields. Sometimes there only schemes or just buttons.
Using those formspecs is the same except setting things works instantly. So by clicking the bottom right on the scheme in the formspec below directly places the timer there.
Using those dialogs is the same except setting things works instantly. So by clicking the bottom right on the scheme in the dialog below directly places the timer there.
![Position](screenshots/position.png)
Where needed, apply buttons are placed. So instead of having to leave the formspec via the navigation buttons at the bottom to apply the changes simply click the apply button to have the value applied.
Where needed, apply buttons are placed. So instead of having to leave the dialog via the navigation buttons at the bottom to apply the changes simply click the apply button to have the value applied.
![Timer Format](screenshots/timer_format.png)
In the timer format configuration formspec shown above a text area is used where pressing enter goes to a new line so a button for applying the changes is shown.
In the timer format configuration dialog shown above a text area is used where pressing enter goes to a new line so a button for applying the changes is shown.
## Custom Timer
mTimer comes with a freely configurable custom timer that can run in three different modes and shows its current state and time as applicable. The formats for the three states can be configured individually.
The four time unput fields on the middle left are used for days, hours, minutes, and seconds and the table with the variables shows the set value and not the current value because the current value changes depending on the timer state and mode.
The four time input fields on the middle left are used for days, hours, minutes, and seconds and the table with the variables shows the set value and not the current value because the current value changes depending on the timer state and mode.
![Custom Timer](screenshots/custom_timer.png)
@ -109,18 +109,28 @@ mtimer_custom_timer_mode = countdown
The `mtimer_timer_format` value allows a special replacement variable. All occurrences of a literal `{_n}` will be replaced with a newline. This is done because configuration values cannot have a newline. All `S()` values are translated. Unfortunately currently you cannot set translatable string in configuration options.
## Known Issues
## Known issues
### Formspecs Look Weird
### Formspecs look weird
On very small screens the configuration formspecs might look very crammed with text being cut off or overlaying other text. This is due to how formspecs work and is not fixable without massive Minetest engine changes.
On very small screens the configuration dialogs might look very crammed with text being cut off or overlaying other text. This is due to how formspecs work and is not fixable without massive Minetest engine changes.
Same in the other direction: On very large screens the formspecs seem unnecessary huge with much empty space. Same here: This is not fixable without re-implementing formspec generation from scratch in Minetest.
Same in the other direction: On very large screens the dialogs seem unnecessary huge with much empty space. Same here: This is not fixable without re-implementing formspec generation from scratch in Minetest.
mTimer was tested with resolutions from 1024×768 up to 2560×1440 with 20px font and GUI scaling of 1.5. Since different font sizes and GUI scaling are somewhat broken in Minetest when it comes to formspecs the later was usable but did not look that good.
### Formspec Language Does Not Match Game Language
### Dialog language does not match dame language
Simple: The mod was not translated to the language you’re using. Feel free to translate it and file a pull request. I’d be happy to merge it.
Currently German (`language = de` in `minetest.conf`) and Italian (`language = it`) are supported as translation language and English being the default and Italian being slightly out of date.
### HUD element scale slider does not reset
The slider dialog is created using a formspec scroll bar element. For some reason it seems not to be possible to properly reload the formspec programmatically so the actual value is used.
Currently there is nothing that can be done in order to instantly reset the formspec as needed to reflect the state of the dialog after the value was reset to default. The HUD element itself is reset and when re-opening the HUD element scale dialog the correct value is shown again.
### When unchecking the custom timer type nothing is enabled
This is a visual glitch. The timer operates in the last selected mode. The checkmark re-appears when closing and re-opening the custom timer dialog.