minetest / minetest_docs Goto Github PK

View Code? Open in Web Editor NEW

22.0 22.0 12.0 2.78 MB

Minetest Engine documentation (Work in progress. Meanwhile, please refer to lua_api.txt and dev.minetest.net)

License: Other

minetest_docs's Introduction

Minetest

Minetest is a free open-source voxel game engine with easy modding and game creation.

Further Documentation
Default Controls
Paths
Configuration File
Command-line Options
Compiling
Docker
Version Scheme

Further documentation

Website: https://www.minetest.net/
Wiki: https://wiki.minetest.net/
Forum: https://forum.minetest.net/
GitHub: https://github.com/minetest/minetest/
Developer documentation
doc/ directory of source distribution

Default controls

All controls are re-bindable using settings. Some can be changed in the key config dialog in the settings tab.

Button	Action
Move mouse	Look around
W, A, S, D	Move
Space	Jump/move up
Shift	Sneak/move down
Q	Drop itemstack
Shift + Q	Drop single item
Left mouse button	Dig/punch/use
Right mouse button	Place/use
Shift + right mouse button	Build (without using)
I	Inventory menu
Mouse wheel	Select item
0-9	Select item
Z	Zoom (needs zoom privilege)
T	Chat
/	Command
Esc	Pause menu/abort/exit (pauses only singleplayer game)
+	Increase view range
-	Decrease view range
K	Enable/disable fly mode (needs fly privilege)
J	Enable/disable fast mode (needs fast privilege)
H	Enable/disable noclip mode (needs noclip privilege)
E	Aux1 (Move fast in fast mode. Games may add special features)
C	Cycle through camera modes
V	Cycle through minimap modes
Shift + V	Change minimap orientation
F1	Hide/show HUD
F2	Hide/show chat
F3	Disable/enable fog
F4	Disable/enable camera update (Mapblocks are not updated anymore when disabled, disabled in release builds)
F5	Cycle through debug information screens
F6	Cycle through profiler info screens
F10	Show/hide console
F12	Take screenshot

Paths

Locations:

bin - Compiled binaries
share - Distributed read-only data
user - User-created modifiable data

Where each location is on each platform:

Windows .zip / RUN_IN_PLACE source:
- bin = bin
- share = .
- user = .
Windows installed:
- bin = C:\Program Files\Minetest\bin (Depends on the install location)
- share = C:\Program Files\Minetest (Depends on the install location)
- user = %APPDATA%\Minetest or %MINETEST_USER_PATH%
Linux installed:
- bin = /usr/bin
- share = /usr/share/minetest
- user = ~/.minetest or $MINETEST_USER_PATH
macOS:
- bin = Contents/MacOS
- share = Contents/Resources
- user = Contents/User or ~/Library/Application Support/minetest or $MINETEST_USER_PATH

Worlds can be found as separate folders in: user/worlds/

Configuration file

Default location: user/minetest.conf
This file is created by closing Minetest for the first time.
A specific file can be specified on the command line: --config <path-to-file>
A run-in-place build will look for the configuration file in location_of_exe/../minetest.conf and also location_of_exe/../../minetest.conf

Command-line options

Use --help

Compiling

Docker

Version scheme

We use major.minor.patch since 5.0.0-dev. Prior to that we used 0.major.minor.

Major is incremented when the release contains breaking changes, all other numbers are set to 0.
Minor is incremented when the release contains new non-breaking features, patch is set to 0.
Patch is incremented when the release only contains bugfixes and very minor/trivial features considered necessary.

Since 5.0.0-dev and 0.4.17-dev, the dev notation refers to the next release, i.e.: 5.0.0-dev is the development version leading to 5.0.0. Prior to that we used previous_version-dev.

minetest_docs's People

Contributors

Stargazers

Watchers

Forkers

appgurueu josiahwi minetest-j45 benrob0329 wsor4035 rollerozxa greenxenith randomtesting1234 alexxxisanchezz standardgalactic veprogames thor10

minetest_docs's Issues

Document profiler

As well as other profiling methods (LuaJIT, simply wrapping in get_us_time etc)

Add guides

Ideas for guides:

How to properly sandbox Lua
How to: Inter-process communication (IPC)

Document ItemStack returning functions

on_use etc. Include a note that prevents people from making the common mistake of trying to modify the inventory before/instead of returning the itemstack they want to be set.

Match lua_api.txt coverage (mega tracker)

Namespaces

minetest

Global Tables

Constants

math (done)

math.factorial
math.hypot
math.round
math.sign

string (done)

string.split
string:trim

table (done)

vector (done)

Methods

AreaStore

HTTPApi

minetest.request_http_api
HTTPApi.fetch
HTTPApi.fetch_async
HTTPApi.fetch_async_get

InvRef

ItemStack (done)

ItemStackMetaRef (done)

ItemStackMetaRef:set_tool_capabilities

MetaDataRef (done)

ModChannel (done)

NodeMetaRef (done)

NodeMetaRef:get_inventory
NodeMetaRef:mark_as_private

NodeTimerRef

ObjectRef

PlayerRef

PcgRandom

PcgRandom
PcgRandom:next
PcgRandom:rand_normal_dist

PerlinNoise

minetest.get_perlin
PerlinNoise
PerlinNoise:get_2d
PerlinNoise:get_3d

PerlinNoiseMap

PseudoRandom

PseudoRandom
PseudoRandom:next

Raycast (done)

Raycast
minetest.raycast
Raycast:next

SecureRandom

SecureRandom
SecureRandom:next_bytes

Settings

VoxelArea (done)

VoxelManip

Other

Formspec Elements

Texture Modifiers (done)

Document translation options

See https://dev.minetest.net/Translation

This project seems to be dying from inactivity (we're falling behind latest master in terms of docs more and more rather than closing the gap as per #16) and I'd like to discuss how we should proceed. Possible options I see:

Archive the repo, bury the project, cut the losses.
Try to revive the project, get it rolling again. The last attempt at this ("first sprint": #38) failed. It seems we, the project members, don't have adequate resources to work on this currently.
This brings me to the next point: Should we try to attract "documentators" to keep this project going?
Alternatively, if we decide to bury this project, we should not let the effort so far go to waste. Should we:
- Try to get it merged into the minetest Markdown docs (requires conversion to Markdown, will send us back to PR hell)?
- Preserve it by putting it on the wiki (it seems @rollerozxa has been working on this)?

What do you think: Where is this project headed, where should it be headed?

Relicense to CC-BY-SA (3.0/4.0?)

The choice of CC-BY 4.0 for this project was short sighted as all other current documentation (Minetest engine doc/ including lua_api.txt and the Minetest Wiki) are licensed under CC-BY-SA 3.0. We should relicense to CC-BY-SA (3.0/4.0?) so we can make use of these resources for the project.

Document pointed things

See https://dev.minetest.net/pointed_thing

`physical` default appears to be `false`

https://github.com/minetest/minetest_docs/blob/master/doc/object_properties.adoc#physical

CSS for generated HTML uses Unicode Private Use Area characters, makes ugly boxes

I.e. I have ugly boxes for warning messages, see screenshot: https://mister-muffin.de/p/ShP2.png

Solution: Use appropriate Unicode characters here. Which ones would that be?

Config Template Blocked by Safe Mode

There is not a whole lot that needs to be said about this. We probably do not want to run the production server in unsafe mode, but the next level up, safe mode, does not permit accessing ancestor directories of the document.

Edit: We can specify a base directory for the conversion, but we get this warning when doing so: asciidoctor: WARNING: include file has illegal reference to ancestor of jail; recovering automatically

Missing "getting started" page

Purposes:

Linking some "prerequisites";
Clearly stating which audience which docs are aiming at (programmers)

Template is overly verbose and at times misleading

Why all the {type-<typename>} macros rather than just <typename>?
Why are properties documented as Vehicle.property? This implies that they were "class variables" (static in Java) rather than per-instance fields. I suggest documenting them just as property to reduce redundancy. Why do fields not use the table format used for arguments & returns?
"Usage" is redundant with arguments + returns
Methods shouldn't be referred to as Vehicle:method as this may be confused with the class:new syntax often used for Lua OOP which MT doesn't use. Vehicle shouldn't be littered all over the document.
Method names should be in monospace.
Table styling should not be all over the place.

Build instructions are missing

It is entirely unclear to me how to build this project.

I am pretty sure the build is just a few commands, but it is not documented.

Update note about texture modifier memleaks

Verify that minetest/minetest#12514 fixes texture modifier memleaks (does it?)

Create comprehensive "what is where" source code overview

Currently, there is no overview for the engine structure that tells you which code lies where, which makes it hard for new contributors to work their way into the engine.

Pull request merging policy

Licensing

We have to choose a license. Suggestions so far:

LGPLv2.1 (like Minetest and implicitly the existing lua_api.txt)
MIT (should be compatible with LGPLv2.1)
CC BY 4.0
CC BY-SA 4.0

My personal preference would be MIT.

Sprint 1

As proposed in the IRC channel and suggested by benrob, going to start a 2 week sprint for getting some docs done.

before 8/19/2022 - pick a topic you will be covering
8/19/2022 ~~or before~~ to 8/26/2022 - work on the doc, get it ready for review
8/26/2022 to 9/2/2022 - get your PR reviewed, and review someone else's

List of topics taken:

Document the common pitfalls

The documentation will likely always lag behind the latest version of the engine, and not everything is thoroughly documented in the first place. But considering that games and mods have various issues related to improper API usage, impacting both players and contributors, a guide covering the most common pitfalls would be very useful.

So instead of sharing empty criticism about how some games and mods are "broken beyond repair", a guide to addressing common issues is the mature thing to do. This helps the entire ecosystem.

Attempting to use set_player_privs incrementally by doing just minetest.set_player_privs(name, {my_priv = true}) and expecting it to grant my_priv (whereas in reality it revokes all privs except for my_priv)
Attempting to use set_player_privs as if a boolean false value was treated as revoking a priv (whereas the privs are a set and thus this is treated as granting the priv): privs.my_priv = false; minetest.set_player_privs(name, privs)

@rollerozxa is being assigned for heretic variable naming inherited from a poorly written Sudoku game.

Recommend Projects

React

A declarative, efficient, and flexible JavaScript library for building user interfaces.
Vue.js

🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
Typescript

TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
TensorFlow

An Open Source Machine Learning Framework for Everyone
Django

The Web framework for perfectionists with deadlines.
Laravel

A PHP framework for web artisans
D3

Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

javascript

JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
web

Some thing interesting about web. New door for the world.
server

A server is a program made to process requests and deliver data to clients.
Machine learning

Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Visualization

Some thing interesting about visualization, use data art
Game

Some thing interesting about game, make everyone happy.

Recommend Org

Facebook

We are working to build community through open source technology. NB: members must have two-factor auth.
Microsoft

Open source projects and samples from Microsoft.
Google

Google ❤️ Open Source for everyone.
Alibaba

Alibaba Open Source for everyone
D3

Data-Driven Documents codes.
Tencent

China tencent open source team.