1  # bjvxlx modpack v0.1.0: blujai831's VoxeLibre extensions
  2  
  3  This is a modpack for [Minetest](https://www.minetest.net). Specifically,
  4  it's for [VoxeLibre](https://content.minetest.net/packages/Wuzzy/mineclone2).
  5  
  6  The mods in this pack have some interdependencies, but for the most part,
  7  they can be used all together or independently (though all of them require
  8  VoxeLibre). They're grouped together as a modpack not for any thematic reason,
  9  but moreso because they come from the same author (myself), operate
 10  on the same Minetest game (VoxeLibre), and use a common codebase. Though,
 11  if I had to describe them as having any cohesive overall theme, I'd say
 12  that *currently*, they're themed mostly around programmable computers,
 13  and the groundwork necessary to make it diegetically plausible to build them
 14  in VoxeLibre.
 15  
 16  Current mods included:
 17  
 18  * `bjvxlx_util`: Library mod for the rest of the pack.
 19  * `bjvxlx_text_shell`: Library mod for a few of the other mods.
 20  * `bjvxlx_lua_access`: Adds chat command `/lua` for an in-game Lua console.
 21  * `bjvxlx_instant_leaf_decay`: Orphaned leaves decay instantly.
 22  * `bjvxlx_sticks_from_saplings`: Tear apart saplings to make sticks.
 23  * `bjvxlx_zombie_leather`: Smelt rotten flesh into leather.
 24  * `bjvxlx_redstone_from_copper`: Convert between redstone and copper.
 25  * `bjvxlx_silicon`: Smelt crystals to get silicon for crafting redstone stuff.
 26  * `bjvxlx_bronze`: Copper and silicon make bronze, an iron substitute.
 27  * `bjvxlx_engineering`: Mostly a library mod. Tech-themed alt crafting system.
 28  * `bjvxlx_computers`: Essentially craftable Lua consoles with data storage.
 29  
 30  ## Installation
 31  
 32  Clone this repository and put the resulting directory `bjvxlx`
 33  in `[minetest dir]/mods`. On Linux, `[minetest dir]` is probably
 34  `~/.minetest`.
 35  
 36  ## Specific features
 37  
 38  ### bjvxlx_util
 39  
 40  Provides facilities for bjvxlx mod init, string manip, iteration, translation,
 41  functional programming, object-oriented programming, sandboxing dynamic code,
 42  and kind-of-transparently treating a portion of a Minetest metadata
 43  or mod storage object as if it were a table. The API is documented
 44  in the source files.
 45  
 46  ### bjvxlx_text_shell
 47  
 48  Streamlines creation of somewhat persistent sessions for formspecs,
 49  particularly command-line-like formspecs. By "somewhat" persistent
 50  I mean the session will survive the player closing the formspec
 51  or even logging off and back on, but will not persist if the server restarts.
 52  
 53  The API is documented in the source files.
 54  Good starting points are `bjvxlx.text_shell.register_shell`
 55  and `bjvxlx.text_shell.get_session`.
 56  
 57  ### bjvxlx_lua_access
 58  
 59  Type `/lua <command>` into chat, replacing `<command>` with your Lua code,
 60  to run your Lua code on the server, or type `/lua` with no argument
 61  for a nicer interface for doing so.
 62  
 63  Note that unless you have privilege `server`, the environment
 64  in which your code is run will be sandboxed: most of the Lua standard library
 65  will be available, but (I hope) not anything that would allow access
 66  to the Minetest game state or to any server OS resources
 67  other than processing power.
 68  
 69  Naturally, it is *not* possible (within reason) for the sandbox to protect
 70  against the possibility of the guest code DoS'ing the server
 71  by entering an infinite loop. That would be rude, so please don't do it.
 72  
 73  There are two main motivations behind this mod:
 74  
 75  * easier mod debugging;
 76  * an easy basis for `bjvxlx_computers`.
 77  
 78  ### bjvxlx_instant_leaf_decay
 79  
 80  With this mod active, once a naturally-generated contiguous region
 81  of leaf blocks first becomes completely isolated from any log blocks,
 82  all leaf blocks in that contiguous region will decay instantaneously,
 83  rather than risk persisting midair until mined manually.
 84  
 85  Leaf blocks are discovered via a 6-direction depth-first traversal
 86  of discrete 3D space from the point where the tree trunk was severed.
 87  
 88  The morale here is that I find cleaning up stray leaf blocks really tedious.
 89  
 90  ### bjvxlx_sticks_from_saplings
 91  
 92  With this mod active, a single sapling may be crafted into 3 sticks.
 93  The morale is to provide an additional use for unneeded saplings
 94  besides as fuel, as well as a quick and realistic way to get sticks.
 95  
 96  ### bjvxlx_zombie_leather
 97  
 98  With this mod active, a single piece of rotten flesh may be smelted
 99  into a single piece of leather. The morale is to obviate the need
100  to kill cows.
101  
102  ### bjvxlx_redstone_from_copper
103  
104  With this mod active, a copper ingot may be crafted into four redstone,
105  and four redstone in a square pattern may be crafted into a copper ingot.
106  
107  There are two morales here:
108  
109  * make copper less useless;
110  * imply copper and redstone are one material, because it's silly they aren't.
111  
112  ### bjvxlx_silicon
113  
114  With this mod active, amethyst shards and nether quartz can both be smelted
115  into silicon. Silicon can be used in alternative recipes
116  for redstone components and other simple-device-like items.
117  It comes in nuggets, ingots, and blocks, like base game metals,
118  but cannot be used to craft armor or tools.
119  
120  There are three morales here:
121  
122  * make amethyst less useless;
123  * provide a basis for `bjvxlx_bronze`;
124  * provide a basis for `bjvxlx_computers`.
125  
126  ### bjvxlx_bronze
127  
128  With this mod active, a silicon nugget and a copper ingot
129  can be crafted together to yield a bronze ingot.
130  Bronze can be used as an alternative to iron in many recipes,
131  including tools, armor, building blocks, and minecart tracks.
132  It comes in nuggets, ingots, and blocks, like base game metals.
133  
134  The morale here is to provide a slightly more renewable way of obtaining
135  what is *effectively* iron. In my opinion, iron is a tiny bit too rare
136  for how essential it is. This also lends another use to copper and amethyst.
137  
138  ### bjvxlx_engineering
139  
140  Provides the "engineering table," a crafting-table-like item
141  that accepts a separate set of recipes. An engineering table's recipes
142  are written on blueprints, which ideally a dependent mod
143  would, say, add to a loot table somewhere or something.
144  
145  An engineering recipe requires not only up to nine consumed ingredients,
146  but also the blueprint for the recipe, which is treated as an ingredient
147  but not consumed, and possibly a specific tool, which is also treated
148  as an ingredient but not consumed. The idea is that your character,
149  who lives in whatever variety of medieval era VoxeLibre takes place in,
150  is unfamiliar with the technology used to craft these more advanced recipes,
151  and needs to continuously consult the blueprint during the crafting process.
152  
153  `bjvxlx_engineering` provides only one blueprint, which is technically
154  not a blueprint: the "engineering dossier." The dossier can be crafted
155  together with an iron block, using ordinary crafting, to produce
156  an engineering table. The dossier does not naturally spawn.
157  Actual engineering recipes, as well as routes for obtaining the dossier
158  and blueprints, are to be provided by dependent mods.
159  
160  The API is documented in the source files. Of particular interest
161  is function `bjvxlx.engineering.register_blueprint`.
162  
163  ### bjvxlx_computers
164  
165  Provides a usable in-game computer, which is essentially
166  just a sandboxed Lua console plus persistent data storage.
167  
168  The computer can be obtained through a long series of engineering recipes.
169  Currently, there is no way to obtain the blueprints for these recipes
170  in survival gameplay. A future mod will address this.
171  
172  The computer's floppy disk inventory can be accessed
173  while it's not receiving redstone power. To be useful,
174  a computer requires at least a MineOS floppy disk
175  (which is not even engineerable, and will in a future mod
176  be made available in a loot table somewhere) inserted into its bootdisk slot,
177  and redstone power input after that. To store data persistently,
178  it must also have a regular floppy disk in at least one of its datadisk slots.
179  
180  Your primary means of interfacing with MineOS is through its Lua shell.
181  The shell API exposes the namespace `os`, which has the following functions:
182  
183  `os.disk(n)`: Get root table of datadisk #`n`. Modifications to this table
184  will persist on the disk. The disk must be inserted and already formatted.
185  
186  `os.format_disk(n)`: Delete all data on datadisk #`n`
187  and create an empty root table. The disk must already be inserted.
188  
189  `os.open(table, key)`: Opens an interface for inputting a multiline string
190  to be saved under `key` in `table`. If `key` already exists in `table`,
191  it must be a string, and in that case, it is loaded
192  into the editing interface; thus, this is also a feasible way
193  to simply *view* a long multiline string.
194  
195  `os.list(table)`: Returns, as multiple return values, all of the keys
196  of the given table. This is your `ls` of sorts.
197  
198  `os.run(script)`: Runs the given string as Lua code.