ToME Wiki
The VFS(Virtual File System)
The first thing to understand about T-Engine 3 is that it uses its own private filesystem that is completly cut off your real filesystem. Now, do not be afraid, this is most simple to grasp.
The VFS is composed of:
a search path list, which contains locations on your real filesystems
a write path, which points to where files will be written
When T-Engines requests a file, say /data/dungeon/traps.lua, the VFS will check each of the directories in the search path until it finds it. Imagine your search path is:
/home/darkgod/.tome/3.0/tome/
/home/games/tome/game/tome/
/home/games/tome/game/
The VFS will check if the file exists in /home/darkgod/.tome/3.0/tome/, let's say it does not, so it checks /home/games/tome/game/tome/, where the file exists, it will be used and /home/games/tome/game/ will just be ignored even if it also contained the requested file.
In plain words this simply means your module can override, if needed, files present in the engine core.
One last thing, the search path list can contain zip files instead of real directories, the VFS will uncompress them on the fly as needed. The file extension is meaningless bu it is recommended to use the following:
.team for modules (T-Engine Archived Module)
.teap for addons (T-Engine Archived Patch)
.tea for anything else (T-Engine Archive)
Now when making a module you do not have to care about the VFS at all, the engine handles and sets it up for you just fine, just be aware of its existence.
A simple module layout
Now a module will needs a few basic files and directories:
/module.lua This is the core of your module, it describes it to the engine
/data/ This directory contains all info about monsters, objects, dungeons, traps, spells, ...
/scripts/ This directory contains all the modules lua scripts, like level generators, quests, new AIs, ...
/file/ This directory contains various pure text files taht your module may need, like intro screens, death messages, rumours, ...
/pref/ The directory contains the 'preference files' that define how things looks, they are especialy important for graphical modes.
/addons/ This directory can be empty, or even not exist, it is meant to contain addons to your module made by other people.
Chatter
NerdanelVampire: I put my module in /home/nerdanel/zothiqband. I have the 3.0.0 alpha compiled in /home/nerdanel/tome3 and Zothiqband put in as a symbolic link at /home/nerdanel/tome3/game/modules/zothiqband so that when I compile a new version I can just put in a new symbolic link and not change anything else. For some reason this doesn't seem to be working. ToME can access my symbolically linked directory just fine but not find any files not copied thre. What's up?
DarkGod: Dunno, the easiest for you is to call your directory zothiqband.team(do not zip it, call the directory like that) and start tome as: tome -M/home/nerdanel/zothiqband.team T-Engine will think this is a module archive and load it, but since the VFS transparently handles archives it doesnt actually matters if it is really one.
NerdanelVampire: Turns out it wasn't the symbolic link after all. Any way I start the module I get a lot of purple tome_dofile_anywhere() errors about things not being found. If I copy over the things that weren't found I get more errors for other files that are linked from the files I copied first. world.map crashes the whole thing seemingly no matter what I do about it.
If wild/world.map isn't there:
error: assertion failed! map wild/world.map loaded, but no map found in running map state! stack traceback: 1: function `assert' [C] 2: method `load' at line 115 [file `/engine/mapload.lua']
If wild/world.map is there:
error: array indexing out of range. stack traceback: 1: `gettable' tag method [C] 2: method `map' at line 308 [file `/engine/mapload.lua'] 3: main of file `/data/wild/world.map' at line 75 4: function `__global_tome_dofile_anywhere' [C] 5: function `p' at line 51 [file `/engine/globals.lua'] 6: function `protect_tome_dofile' at line 30 [file `/engine/globals.lua'] 7: function `tome_dofile_anywhere' at line 51 [file `/engine/globals.lua'] 8: method `load' at line 113 [file `/engine/mapload.lua'] 9: function <72:file `/engine/dungeon.lua'> at line 78 ./tome3: No object kinds!
NerdanelVampire: I got rid of the map error by using the ODE non-map for now, but the "No object kinds" error from init2.c remains. I have no idea where the object kinds error is coming from. I even tried to put my zothiqband directory straight to /game/modules without any symbolic links at all, but I get the exact same errors.
NerdanelVampire: I think I am missing some file I really need. I made a simple test module, and after giving it module.lua, file/news.txt, and data/wild/world.map I am back at the "No object kinds!" territory (with lots of purple error messages) with no idea where to go from there. I've tried copying all sorts of files into Zothiqband but nothing seems to have any effect in giving it "object kinds".
DarkGod: well do you have a /data/items/items.lua file with objects inside ? 
(when you have weird errors it's always a good idea to delete your HOME/.tome/3.0/module/raw/ directory, just in case)
TheFalcon: Errm, pardon this foolish question, but where are savefiles kept...
NerdanelVampire: In my cases I found my savefiles under /home/nerdanel/.tome/3.0. That's on Linux. I don't know about Windows but you could look in a similar place, like My Documents?
On the case of my module, I finally got to the character selection (which bugs out too, by the way) after I added everything in "gods" and "magic". I had already tried copying "items" over among several other directories. I thought the point of the new file thing system was that I wouldn't need to copy everything to get a working module, so that for example in the absence of data/magic the module would revert to using ToME's data/magic, but that doesn't seem to work.
DarkGod: Well sorry for the current lack fo docs, I was busy making T-Engine3 work ;> I was hoping you would make them .. no ? ;> Seriously, there are 2 ways of using the T-Engine:
To make a variant(of a module of course). In this case you must tell T-Engine that your module "extends" the base module. If you want to extend ToME you must add require_module = { "ODE", 1, 0, 0 } to your module.lua file. To test it, make a new directory in modules/ and jsut put a simple modules.lua with a require for ODE in. It will load and play just like ODE.
- To make a new game. Both ToME and ODE are complete modules, they do not require any other modules to be installed. I could release T-Engine with only ODE packaged and it would work just fine.
Most module authors will want to make a full game I believe. So better start from an empty template(ODE is quite empty) and work from there. You can import monsters/items/... fomr ToME if you want but jsut copy the file. Making a variant module is easier for simple changes, but it's a bad idea for big modules.
Savefiles are in HOME/.tome/3.0/module/save/savename in all OSes
NerdanelVampire: How am I going to be able to write documentation when I don't understand a thing myself?
I am intending to end up with a real module, but I think making a variant module is nicer to start with, so I don't have to hunt down all the changes made to alpha level stuff as it matures and copy them over and over again.
I finally got Zothiqband to work even though at the moment it's basically ToME with an unusual calendar and some things like junkart names that are currently invisible.
DarkGod: But that's why you(and others) can write it better than I can: you learn as you go, I know it all, it's hard to explain something you know by heart for 3 years 
CatwhoWalksbyhimself: That's like a Nuclear Physicist telling a student that he has to rediscover all of nuclear physics himself, because he already understands it and it is easier to explain something that you don't know. Nonesense! I am sorry you aren't a good explainer, but you will have to help us learn. This engine, just from my cursory examination, is incrediably deep, but we will never figure out all of its features on our own. Surely there are others who have been working on this why can help? But, reguardless, your answering questions is teaching us, at least a little.
DarkGod: Obviously I'll answer questions I mean once I do, people can make a doc from them