From da0f8cd6b54e2ddb3c2652fe88c0b9f8ca54ba78 Mon Sep 17 00:00:00 2001 From: Xeno333 <149852758+Xeno333@users.noreply.github.com> Date: Tue, 24 Jun 2025 04:49:59 -0500 Subject: [PATCH] Add documentation index for `doc/` as `README.md`, and small docs fixes (#16253) --- doc/README.md | 60 ++++++++++++++++++++++++ doc/developing/README.md | 11 +++-- doc/developing/{misc.md => profiling.md} | 2 +- doc/fst_api.txt | 10 ++-- doc/protocol.txt | 3 +- 5 files changed, 75 insertions(+), 11 deletions(-) create mode 100644 doc/README.md rename doc/developing/{misc.md => profiling.md} (99%) diff --git a/doc/README.md b/doc/README.md new file mode 100644 index 000000000..894e5d75d --- /dev/null +++ b/doc/README.md @@ -0,0 +1,60 @@ +# Documentation + +This directory contains mostly reference documentation for the Luanti engine. +For a less prescriptive and more guiding documentation, also look at: +https://docs.luanti.org + +Note that the inner workings of the engine are not well documented. It's most +often better to read the code. + +Markdown files are written in a way that they can also be read in plain text. +When modifying, please keep it that way! + +Here is a list with descriptions of relevant files: + +## Server Modding + +- [lua_api.md](lua_api.md): Server Modding API reference. (Not only the Lua part, + but also file structure and everything else.) + If you want to make a mod or game, look here! + A rendered version is also available at . +- [builtin_entities.md](builtin_entities.md): Doc for entities predefined by the + engine (in builtin), i.e. dropped items and falling nodes. + +## Client-Side Content + +- [texture_packs.md](texture_packs.md): Layout and description of Luanti's + texture packs structure and configuration. +- [client_lua_api.md](client_lua_api.md): Client-Provided Client-Side Modding + (CPCSM) API reference. + +## Mainmenu scripting + +- [menu_lua_api.md](menu_lua_api.md): API reference for the mainmenu scripting + environment. +- [fst_api.txt](fst_api.txt): Formspec Toolkit API, included in builtin for the + main menu. + +## Formats and Protocols + +- [world_format.md](world_format.md): Structure of Luanti world directories and + format of the files therein. + Note: If you want to write your own deserializer, it will be easier to read + the `serialize()` and `deSerialize()` functions of the various structures in + C++, e.g. `MapBlock::deSerialize()`. +- [protocol.txt](protocol.txt): *Rough* outline of Luanti's network protocol. + +## Misc. + +- [compiling/](compiling/): Compilation instructions, and options. +- [ides/](ides/): Instructions for configuring certain IDEs for engine development. +- [developing/](developing/): Information about Luanti development. + Note: [developing/profiling.md](developing/profiling.md) can be useful for + modders and server owners! +- [android.md](android.md): Android quirks. +- [direction.md](direction.md): Information related to the future direction of + Luanti. Commonly referred to as the roadmap document. +- [breakages.md](breakages.md): List of planned breakages for the next major + release, i.e. 6.0.0. +- [docker_server.md](docker_server.md): Information about our Docker server + images in the ghcr. diff --git a/doc/developing/README.md b/doc/developing/README.md index 80e531bea..a2d19cd9a 100644 --- a/doc/developing/README.md +++ b/doc/developing/README.md @@ -2,7 +2,7 @@ ## Luanti Documentation -Some important development docs are found in the Luanti Documentation: https://docs.luanti.org/ +Some important development docs are found on the docs site: https://docs.luanti.org/ Notable pages: @@ -11,13 +11,14 @@ Notable pages: - [Changelog](https://docs.luanti.org/about/changelog/) - [Organisation](https://docs.luanti.org/for-engine-devs/organization/) - [Code style guidelines](https://docs.luanti.org/for-engine-devs/code-style-guidelines/) + and [Lua code style guidelines](https://docs.luanti.org/for-engine-devs/lua-code-style-guidelines/) ## In this folder -- [Developing minetestserver with Docker](docker.md) -- [Android tips & tricks](android.md) -- [OS/library compatibility policy](os-compatibility.md) -- [Miscellaneous](misc.md) +- [docker.md](docker.md): Developing minetestserver with Docker +- [android.md](android.md): Android tips & tricks +- [os-compatibility.md](os-compatibility.md): OS/library compatibility policy +- [profiling.md](profiling.md): Profiling instructions ## IRC diff --git a/doc/developing/misc.md b/doc/developing/profiling.md similarity index 99% rename from doc/developing/misc.md rename to doc/developing/profiling.md index 5992946cb..2c334183b 100644 --- a/doc/developing/misc.md +++ b/doc/developing/profiling.md @@ -1,4 +1,4 @@ -# Miscellaneous +# Profiling ## Profiling Luanti on Linux with perf diff --git a/doc/fst_api.txt b/doc/fst_api.txt index c12093d91..9170ecf8e 100644 --- a/doc/fst_api.txt +++ b/doc/fst_api.txt @@ -3,8 +3,10 @@ Formspec toolkit api 0.0.3 Formspec toolkit is a set of functions to create basic ui elements. +You can find the files in builtin/fstk/. -File: fst/ui.lua + +File: fstk/ui.lua ---------------- ui.lua adds base ui interface to add additional components to. @@ -25,7 +27,7 @@ ui.find_by_name(name) --> returns component or nil ^ find a component within ui ^ name: name of component to look for -File: fst/tabview.lua +File: fstk/tabview.lua --------------------- tabview_create(name, size, tabheaderpos) --> returns tabview component @@ -92,7 +94,7 @@ methods: * icon: path to icon * on_click(tabview): callback function -File: fst/dialog.lua +File: fstk/dialog.lua --------------------- Only one dialog can be shown at a time. If a dialog is closed it's parent is gonna be activated and shown again. @@ -129,7 +131,7 @@ members: - parent ^ parent component to return to on exit -File: fst/buttonbar.lua +File: fstk/buttonbar.lua ----------------------- buttonbar_create(name, pos, size, bgcolor, cbf_buttonhandler) diff --git a/doc/protocol.txt b/doc/protocol.txt index b0d4a78f7..7aafb0de9 100644 --- a/doc/protocol.txt +++ b/doc/protocol.txt @@ -3,7 +3,8 @@ Updated 2011-06-18 A custom protocol over UDP. Integers are big endian. -Refer to connection.{h,cpp} for further reference. +Refer to network/mtp/internal.h, network/networkprotocol.{h,cpp}, and +server/clientiface.h for further reference. Initialization: - A dummy reliable packet with peer_id=PEER_ID_INEXISTENT=0 is sent to the server: