diff --git a/docs/README.md b/docs/README.md index 20f5a10..287e298 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,30 +1,51 @@ > [!CAUTION] -> this application is under active development and it is not recommended to use yet. +> This application is __not__ ready for usage, and shouldn't be used. +> It is under active development and most features are considered "béta", +> Once a pre-release, or release has been created in [the release tab](https://github.com/thepigeongenerator/mcaselector-lite/releases), +> it is ready for general usage and testing. -# mca selector lite -A from-scratch rewrite of [mcaselector](https://github.com/Querz/mcaselector) in C. +# MCA-Selector-Lite +A from-scratch rewrite of [MCA-Selector](https://github.com/Querz/mcaselector) in C. [![licence](https://img.shields.io/github/license/thepigeongenerator/mcaselector-lite.svg)](https://github.com/thepigeongenerator/mcaselector-lite/blob/main/COPYING) [![issues](https://img.shields.io/github/issues/thepigeongenerator/mcaselector-lite.svg)](https://github.com/thepigeongenerator/mcaselector-lite/issues/) -## what does it do -MCA selector lite is a tool used to edit [region files](https://minecraft.wiki/w/Region_file_format) of your [Minecraft java](https://minecraft.wiki/w/Java_Edition) worlds. -This is useful for reducing world size, general world management, perhaps copying chunks from one world to another or various other administrative tasks. -Although not the intended main use case, it is also possible to use this tool to view the world map. Though, it is recommended to use something like [dynmap](https://dynmap.wiki.gg/wiki/Home) instead (if applicable). +## What does it do +MCA-Selector-Lite is a tool used to edit [region files](https://minecraft.wiki/w/Region_file_format) +of your [Minecraft Java](https://minecraft.wiki/w/Java_Edition) worlds. +This is useful for reducing world size, general world management, +perhaps copying chunks from one world to another or various other administrative tasks. +Although not the intended main use case, it is also possible to use this tool to view the world map. +Though, it is recommended to use something like [dynmap](https://dynmap.wiki.gg/wiki/Home) instead (if applicable). -## why does this project exist? -MCA selector is a tool written in Java. Where it depends upon JRE21 and JavaFX. Where the application is primarily developed for Windows users, where other platforms get a `.jar` file, which can at times be clunky to work with. -The goal of this project is to create a version of the original MCA selector, but written in C, leveraging the improved performance due to native execution and more low-level control. -I have picked C as the language for the core portions of the application, where I prefer fine-grained control with little abstractions. -This version is not intended to serve to entirely replace MCA selector, just to offer an alternative. Both tools will have their strengths and weaknesses. +## Why does this project exist? +MCA-Selector is a tool written in Java. Which, at the time of writing depends upon JRE21 and JavaFX. +Where the application is primarily developed for Windows users, where other platforms get a `.jar` file. +I personally find this clunky to work with, and isn't too clean to install. +The goal of this project is to provide an alternative for MCA-Selector, +applying C to have a focus on performance and minimalism. +I chose C, since it is my preferred language to work in & aligns with how I personally view software. +I may decide to use another language, such as C++ for UI work, but the central functionality shall be C. +The project is still under active development, the main part that I plan to offer with the tool is +chunk deletion, world map viewing, and filtering. From there I may expand to offer more functionality +with MCA-Selector, or go in my own direction. -# planned features -- [ ] (very basic) world map viewing (Y level + surface) -- [ ] filtering chunks based on time spent in them -- [ ] chunk-level removal of data. -- [ ] CLI-only version -- [ ] (idea) change chunk compression -- [ ] (idea) view chunk metadata -- [ ] (idea) change chunk sNBT (this'll be tricky to add) -*note that entries marked with `(idea)` aren't guaranteed to be implemented. -Due to their viability and usefulness is still to be measured.* +# Roadmap +- [ ] First, I shall focus on writing code to view + chunks, creating a map of the blocks. The code shall + produce a [ppm](https://en.wikipedia.org/wiki/Netpbm) file of a respective Y level. + This is to verify whether the binary parsing works correctly. It is intended to support + both `.mca` and `.mcr` files, and various levels of compression. +- [ ] This shall expand into a "mode" that filters the chunks based on player time, + further testing the NBT parsing capabilities, and deletion of chunks. +- [ ] A GUI shall be built, which is still unclear how this'll be implemented. + For starters, the GUI shall purely provide viewing capabilities, at which point the roadmap + shall be updated for features such as chunk selection, et cetera. + +# Miscellaneous planned features: +*note that these entries aren't guaranteed to be implemented. +Due to their viability and usefulness still needing to be measured.* +- Changing chunk compression +- View chunk metadata +- Change chunk sNBT +- "Upgrading" `.mcr` regions to `.mca`. diff --git a/docs/dev/correct-c.md b/docs/dev/correct-c.md deleted file mode 100644 index 2bf1cc2..0000000 --- a/docs/dev/correct-c.md +++ /dev/null @@ -1,13 +0,0 @@ -# Correct C -A monster list about bad code practices for the absolute beginners. -Things obviously should be taken with a grain of salt, just stating the obvious. - -- Functions without parameters will be defined with `void` in the parameter list, as opposed to leaving it empty. (e.i. `(void)` rather than `()`) -- (public-facing) names mustn't be prefixed with `_`, this is a reserved identifier. -- `typedef`s mustn't be suffixed with `_t`, this is a POSIX reserved identifier. -- `typedef`s are discouraged, unless the name alias is clear in what it stores. (e.i. `u32` for a 32 bit unsigned integer) -- Functions should do one thing, and do it well. -- `inline` functions should serve as a replacement for macro definitions, don't put things in here that you wouldn't put in a macro. (block ≤5 lines) -- Mark all implementations in a `*.c` file with `static` if there isn't a matching definition in a `*.h` file. (unless there's a clear reason to) -- When a function parameter takes in a pointer, and does not modify the pointed at data, a const pointer should be used. (`const int *ptr`) -- Try to limit yourself at ~112 columns, but generally avoid overly long lines. diff --git a/docs/dev/styleref.md b/docs/dev/styleref.md deleted file mode 100644 index 78a32a2..0000000 --- a/docs/dev/styleref.md +++ /dev/null @@ -1,34 +0,0 @@ -# mcaselector-lite style reference -## contents -- [recommended tools](#recommended-tools) -- [code information](#code-information) -- [style guide](#style-guide) - -### recommended tools -- gcc -- git (duh) -- clang-format -- clang-tidy -- linux / unix-like machine - -### code information -The project is written in the [GNU dialect](https://gcc.gnu.org/onlinedocs/gcc/C-Dialect-Options.html) of [C99](https://www.en.cppreference.com/w/c/99.html). -Where we have dependencies on: -| library | summary | -|:----------------------------------|:--------------------------------------------------------| -| [libarchive](libarchive.org) | compression / decompression of various formats. | -| [glfw](https://www.glfw.org/) | window creation / input handling. | -| [openGL](https://www.opengl.org/) | hardware accelleration, for handling graphics. | - -It is intended to be platform-agnostic, within reason. But the main focus is for [Linux](https://wikipedia.org/wiki/Linux) systems with [x86_64](https://wikipedia.org/wiki/X86-64) architecture. -Within [types.h](/src/types.h) there live definitions for fixed-width integer types. - -### style guide -- Code must be written correctly, read [Correct C](./correct-c.md) if more information is required. -- `snake_casing` is used, with no [Hungarian notation](https://en.m.wikipedia.org/wiki/Hungarian_notation). (macros are all-uppercase, with a few exceptions) -- [K&R style braces/indentation](https://en.wikipedia.org/wiki/Indentation_style) should be used. -- For indentation tabs are used, and are assumed to be 8 spaces wide. For alignment spaces should be used. -- A space should precede a pointer `*`. Where it is attached to the name, rather than the type. For `const` clarity, and chains such as: `u8 *a, *b, *c;`. This is true for functions as well: `void *malloc(size_t n);` -- Generally speaking, British spelling is preferred. Define potential macros for, or when using alternate dialects. -- Grammar should be correct. (`don't` or `do not`, not `dont`) -- Commits should attempt to convey clearly what is being changed, for the sanity of the maintainer(s).