Lost Souls directory structure

From LSWiki

Revision as of 10:00, 9 January 2007 (edit) Chaos (Talk | contribs) (→/mod) ← Previous diff		Current revision (18:11, 23 April 2008) (edit) Chaos (Talk | contribs)
Line 1:		Line 1:
	This structure of this file mirror the LS directory structure. If you don't know how to navigate the directory structure, please read the [[Developer Primer]].		This structure of this file mirror the LS directory structure. If you don't know how to navigate the directory structure, please read the [[Developer Primer]].
-	This page is going to need a lot more work, but it's worthwhile work, especially since I don't actually the actual organizational principles behind half this stuff.	+	Occasionally you will see references to "the lib" and "Ain Soph". "Lib" is short for "mudlib", which is the set of files that the MUD uses as a base to work from. The official name of the mudlib that Lost Souls runs under is Ain Soph. There is a distinction between "lib" and "content" code; particular projects in the game are content, while the abstract support for rooms, items, and so on that they draw on is lib code. Or, to put it another way, a particular broadsword is content, while the general concept of broadswords is lib code.
	==/d==		==/d==
-	This is where the world is. The "d" stands for "domain", which apparently used to mean something. Chaos claims that this stands for "deployed", but we all know he's a dirty liar.	+	This is where the majority of content is. The "d" stands for "domain", which apparently used to mean something. Chaos claims that this stands for "deployed", but we all know he's a dirty liar.
-	Read access [[privilege]]: [[read_d]]	+	Read access [[privileges|privilege]]: [[privileges#read_d|read_d]]
-	Write access [[privilege]]: [[write_d]]	+	Write access [[privileges|privilege]]: [[privileges#write_d|write_d]]
	===/d/Affiliations===		===/d/Affiliations===
	This is where affiliations (associations, guilds, offices, racial and other faculties).		This is where affiliations (associations, guilds, offices, racial and other faculties).
-	Read access [[privilege]]: [[read_sensitive]]	+	Read access [[privileges|privilege]]: [[privileges#read_sensitive|read_sensitive]]
-	Write access [[privilege]]: [[write_sensitive]]	+	Write access [[privileges|privilege]]: [[privileges#write_sensitive|write_sensitive]]
	===/d/Almeria===		===/d/Almeria===
Line 26:		Line 26:
	Things that don't belong elsewhere, like projects that are primarily about items (Lzrelekoi) or wandering areas (the Vanishing Tower).		Things that don't belong elsewhere, like projects that are primarily about items (Lzrelekoi) or wandering areas (the Vanishing Tower).
-	===/d/(various planes)===	+	===/d/''Various''===
-	Like Almeria, except not on Almeria.	+	Like Almeria, except not Almeria. Includes placeholders for other continents, some partially functional (/d/Tenochlan), others less so (/d/Akalahai), still others not really at all (/d/Esartur); other sorts of region (/d/Astra, which is meant to contain the Prime plane's outer space); and other planes of existence (/d/Exoma, /d/Umbra, /d/Amber).
	==/daemon==		==/daemon==
-	This is where daemons are. What are daemons you ask? Good question. Basically I think they are objects that control, handle, and store data. Right?	+	''Twilight writes:'' This is where daemons are. What are daemons you ask? Good question. Basically I think they are objects that control, handle, and store data. Right?
-	Read access [[privilege]]: [[read_lib]]	+	''Chaos responds:'' Something like that. Our daemons are probably best understood by reference to Unix system daemons, which are programs that run continuously (usually) and handle some particular task; the most popular daemon is the HTTP daemon, or web server. Our daemons are similar: they're objects that hang out and handle some particular function. ''/daemon/armour'' manages the armour subsystem, tracking the armour type and armour style definitions; ''/daemon/weapons'' manages the weapon subsystem, tracking weapon types, weapon sizes, and ammunition types. These are examples of a class of daemon called '''broker daemons''' because their main function is handling definition objects and brokering requests for them; they're mainly found in /daemon. '''Control daemons''' are another major class; these live in the ~Project/dmn directories of individual projects, each serving as a central manager for its project. Other daemons just package up some similar functionality, such as ''/daemon/time''; some manage ongoing or specific-purpose processes of the game, such as ''/daemon/cron'', ''/daemon/autoheal'', and ''/daemon/shutdown''.
-	Write access [[privilege]]: [[write_lib]]	+	Two of the universal characteristics of daemons is that they are never cloned and they are never in-game objects. I can conceive of circumstances that could create an arguably legitimate exception to the former, but not the latter.
		+
		+	If you need to refer to a daemon that lives in /daemon in code, you will almost always be using the "service" macros for them, defined in ''/lib/services.h'' and its specific-purpose relatives in the ''/lib/services'' directory, which look like Daemon_Time, Daemon_Autoheal, Daemon_Shutdown, and so on. Another daemon, ''/daemon/services'', manages these. Besides being prettier than string pathnames, these use a special mechanism to make them faster than other methods you might use for referring to daemons.
		+
		+	Read access [[privileges|privilege]]: [[privileges#read_lib|read_lib]]
		+
		+	Write access [[privileges|privilege]]: [[privileges#write_lib|write_lib]]
	==/def==		==/def==
-	This is where definition files reside. Definitions are abstract files that determine certain generic properties of particular files. Races, anatomies, weapon types, damage types, are all examples of things that have definitions.	+	This is where system-level definition files reside. Definitions are abstract files that determine certain generic properties of particular files. Races, anatomies, weapon types and damage types are all examples of things that have definitions. This is a good directory to explore to see how the lib is set up.
-	Read access [[privilege]]: [[read_lib]]	+	Read access [[privileges|privilege]]: [[privileges#read_lib|read_lib]]
-	Write access [[privilege]]: [[write_lib]]	+	Write access [[privileges|privilege]]: [[privileges#write_lib|write_lib]]
	==/etc==		==/etc==
-	A few general lib files are here, like item.h	+	A few header files are here, like item.h. This directory is mostly unused and is pretty much on its way out, but the basic idea of it once was that it would container header files that were strongly related to a particular instance of the Ain Soph lib rather than to the core of the lib itself.
		+
		+	Read access [[privileges|privilege]]: [[privileges#read_lib|read_lib]]
		+
		+	Write access [[privileges|privilege]]: [[privileges#write_lib|write_lib]]
	==/lib==		==/lib==
-	More particular, but still very general, lib files are here. Project lib files can usually be found in /d/Almeria/lib, or /d/Affiliations/lib, or something of that sort.	+	This is the main location for Ain Soph lib header files. Most of the .h files you will ever use are found here. Project header files can usually be found in /d/Almeria/lib, or /d/Affiliations/lib, or something of that sort.
		+
		+	Read access [[privileges|privilege]]: [[privileges#read_lib|read_lib]]
		+
		+	Write access [[privileges|privilege]]: [[privileges#write_lib|write_lib]]
	===/lib/dev===		===/lib/dev===
-	This is where developer work-in-progress lib files go; everyone has write access to this directory.	+	This is where developer work-in-progress project header files go. It is set up to be writable by ordinary developers. It perpetually is in serious need of cleaning out.
		+
		+	Read access [[privileges|privilege]]: [[privileges#standard|standard]]
		+
		+	Write access [[privileges|privilege]]: [[privileges#standard|standard]]
	===/lib/descriptors===		===/lib/descriptors===
	This is where the header files that are automatically generated by the descriptor definitions in /def/descriptor are kept. Most header files are manually maintained; these are unusual in being created by the system.		This is where the header files that are automatically generated by the descriptor definitions in /def/descriptor are kept. Most header files are manually maintained; these are unusual in being created by the system.
		+
		+	===/lib/services===
		+	This directory contains header files created by ''/daemon/services'' to provide optimized access to "service" functions provided by various system daemons and descriptor definitions. As an example, ''/lib/services/services_affiliations.h'' is automatically generated based on information extracted from ''/daemon/affiliations''; it provides macros for addressing ''/daemon/affiliations'' itself and for using some service functionality provided by it.
	==/mod==		==/mod==
	This hierarchy contains component modules, mainly to be assembled into complete inheritables by things in /std.		This hierarchy contains component modules, mainly to be assembled into complete inheritables by things in /std.
-	Read access [[privilege]]: [[read_lib]]	+	Read access [[privileges|privilege]]: [[privileges#read_lib|read_lib]]
-	Write access [[privilege]]: [[write_lib]]	+	Write access [[privileges|privilege]]: [[privileges#write_lib|write_lib]]
	==/obj==		==/obj==
-	This hierarchy mainly contains files that are intended to be physical objects in the game world; weapons, armour, comestibles, and so on. There are a few special cases.	+	This hierarchy mainly contains files that are intended to be physical objects in the game world; weapons, armour, comestibles, and so on. Files here mostly represent the intersection of lib and content; they are in-game content that's centralized at the lib level rather than belonging to any particular project. There are a few special-case directories under this hierarchy that are used for notably different purposes, however.
-	Read access [[privilege]]: [[read_lib]]	+	Read access [[privileges|privilege]]: [[privileges#read_lib|read_lib]]
-	Write access [[privilege]]: [[write_lib]]	+	Write access [[privileges|privilege]]: [[privileges#write_lib|write_lib]]
	===/obj/extensions===		===/obj/extensions===
Line 81:		Line 102:
	This is where things like the master object and the simul_efun object are kept -- crucial system things.		This is where things like the master object and the simul_efun object are kept -- crucial system things.
-	Read access [[privilege]]: [[read_secure]]	+	Read access [[privileges|privilege]]: [[privileges#read_secure|read_secure]]
-	Write access [[privilege]]: [[write_secure]]	+	Write access [[privileges|privilege]]: [[privileges#write_secure|write_secure]]
	==/pub==		==/pub==
	This is a public directory hierarchy where files can be exchanged and freely edited, and so on. One interesting subdirectory is /pub/defunct, where we generally put the /w directories of former developers.		This is a public directory hierarchy where files can be exchanged and freely edited, and so on. One interesting subdirectory is /pub/defunct, where we generally put the /w directories of former developers.
		+
		+	Read access [[privileges|privilege]]: [[privileges#read|read]]
		+
		+	Write access [[privileges|privilege]]: [[privileges#standard|standard]]
	==/std==		==/std==
		+	Contains "final product" inheritable and clonable objects. Most of the objects you will use as base inheritables live here: ''/std/room'', ''/std/item'', ''/std/autonomon'', ''/std/daemon'', and so on.
		+
		+	Read access [[privileges|privilege]]: [[privileges#read_lib|read_lib]]
		+
		+	Write access [[privileges|privilege]]: [[privileges#write_lib|write_lib]]
		+
	==/sys==		==/sys==
		+	Contains "system" header files. Generally, these are distinguished from header files that live in /lib by being more strongly related to things in /obj/master (e.g. ''/sys/security.h''), or by being header files provided with the driver rather than defined by the Ain Soph lib (e.g. ''/sys/lpctypes.h''). Two important, possibly poorly placed header files that live here are ''/sys/config.h'', which contains some important lib-level settings, and ''/sys/master.h'', which defines LS_Foo() macros that are mostly for referring to things in /obj.
		+
		+	Read access [[privileges|privilege]]: [[privileges#read_lib|read_lib]]
		+
		+	Write access [[privileges|privilege]]: [[privileges#write_lib|write_lib]]
		+
	==/tmp==		==/tmp==
	A public directory for temporary files. Files in this directory are cleared out periodically.		A public directory for temporary files. Files in this directory are cleared out periodically.
		+
		+	Read access [[privileges|privilege]]: [[privileges#read|read]]
		+
		+	Write access [[privileges|privilege]]: [[privileges#standard|standard]]
	==/txt==		==/txt==
		+	Contains text files of various kinds.
		+
		+	Read access [[privileges|privilege]]: [[privileges#standard|standard]]
		+
		+	Write access [[privileges|privilege]]: [[privileges#write_lib|write_lib]]
		+
		+	===/txt/adm===
		+	Contains files that control administrative elements of the system, such as the file that defines what permissions are required to read and write these various directories.
		+
		+	Read access [[privileges|privilege]]: [[privileges#read_lib|read_lib]]
		+
		+	Write access [[privileges|privilege]]: [[privileges#write_secure|write_secure]]
		+
		+	===/txt/doc===
		+	Developer documentation. Documents retrieved by the 'man' command are pulled from this hierarchy. You should work at becoming familiar with the contents of /txt/doc.
		+
		+	Read access [[privileges|privilege]]: [[privileges#read|read]]
		+
		+	Write access [[privileges|privilege]]: [[privileges#documentation|documentation]]
		+
		+	===/txt/help===
		+	Player documentation. This one of the (fairly numerous) places that the 'help' command pulls information from.
		+
		+	Read access [[privileges|privilege]]: [[privileges#read|read]]
		+
		+	Write access [[privileges|privilege]]: [[privileges#documentation|documentation]]
		+
		+	===/txt/log===
		+	Standard location for system log files. Many of these are quite interesting.
		+
		+	Read access [[privileges|privilege]]: [[privileges#standard|standard]]
		+
		+	Write access [[privileges|privilege]]: [[privileges#write_lib|write_lib]]
		+	====/txt/log/dev====
		+	Standard location for developer log files. The usual filename convention is ''/txt/log/dev/<name>.<topic>''. Your personal error log file is ''/txt/log/dev/<your_name>''.
		+
		+	Read access [[privileges|privilege]]: [[privileges#read_w|read_w]] for others' files, [[privileges#standard|standard]] for your files
		+
		+	Write access [[privileges|privilege]]: [[privileges#write_w|write_w]] for others' files, [[privileges#standard|standard]] for your files
		+
		+	===/txt/web===
		+	The lostsouls.org Web site.
		+
		+	Read access [[privileges|privilege]]: [[privileges#standard|standard]]
		+
		+	Write access [[privileges|privilege]]: [[privileges#write_web|write_web]]
		+
	==/usr==		==/usr==
	User files, mainly incarnos and kept-item save files, are in this hierarchy.		User files, mainly incarnos and kept-item save files, are in this hierarchy.
		+
		+	Read access [[privileges|privilege]]: [[privileges#player_files|player_files]]
		+
		+	Write access [[privileges|privilege]]: [[privileges#player_files|player_files]]
	==/w==		==/w==
	This is where developer workspaces go; your personal directory, ''/w/yourname'', is under this hierarchy. Originally the 'w' stood for 'wizard', back when we used such ill-advised terminology for developers, and the whole 'workspace' thing is just so we don't have to change the directory name.		This is where developer workspaces go; your personal directory, ''/w/yourname'', is under this hierarchy. Originally the 'w' stood for 'wizard', back when we used such ill-advised terminology for developers, and the whole 'workspace' thing is just so we don't have to change the directory name.
-	Read access [[privilege]]: [[read_w]]	+	Read access [[privileges|privilege]]: [[privileges#read_w|read_w]]
-	Write access [[privilege]]: [[write_w]]	+	Write access [[privileges|privilege]]: [[privileges#write_w|write_w]]

---

Current revision

This structure of this file mirror the LS directory structure. If you don't know how to navigate the directory structure, please read the Developer Primer.

Occasionally you will see references to "the lib" and "Ain Soph". "Lib" is short for "mudlib", which is the set of files that the MUD uses as a base to work from. The official name of the mudlib that Lost Souls runs under is Ain Soph. There is a distinction between "lib" and "content" code; particular projects in the game are content, while the abstract support for rooms, items, and so on that they draw on is lib code. Or, to put it another way, a particular broadsword is content, while the general concept of broadswords is lib code.

Contents 1 /d 1.1 /d/Affiliations 1.2 /d/Almeria 1.3 /d/System 1.4 /d/Misc 1.5 /d/Various 2 /daemon 3 /def 4 /etc 5 /lib 5.1 /lib/dev 5.2 /lib/descriptors 5.3 /lib/services 6 /mod 7 /obj 7.1 /obj/extensions 7.2 /obj/interfaces 7.3 /obj/master 8 /pub 9 /std 10 /sys 11 /tmp 12 /txt 12.1 /txt/adm 12.2 /txt/doc 12.3 /txt/help 12.4 /txt/log 12.4.1 /txt/log/dev 12.5 /txt/web 13 /usr 14 /w

/d

This is where the majority of content is. The "d" stands for "domain", which apparently used to mean something. Chaos claims that this stands for "deployed", but we all know he's a dirty liar.

Read access privilege: read_d

Write access privilege: write_d

/d/Affiliations

This is where affiliations (associations, guilds, offices, racial and other faculties).

Read access privilege: read_sensitive

Write access privilege: write_sensitive

/d/Almeria

This is where the main map and the main world is, though it's all in subdirectories. Take a look, it should be pretty clear.

/d/System

This is where Bytehaven is, which is an area with a few handy developer bits like the test character register, and the Banishment tablet. There is also a project called Public that has some 'utility' rooms.

/d/Misc

Things that don't belong elsewhere, like projects that are primarily about items (Lzrelekoi) or wandering areas (the Vanishing Tower).

/d/Various

Like Almeria, except not Almeria. Includes placeholders for other continents, some partially functional (/d/Tenochlan), others less so (/d/Akalahai), still others not really at all (/d/Esartur); other sorts of region (/d/Astra, which is meant to contain the Prime plane's outer space); and other planes of existence (/d/Exoma, /d/Umbra, /d/Amber).

/daemon

Twilight writes: This is where daemons are. What are daemons you ask? Good question. Basically I think they are objects that control, handle, and store data. Right?

Chaos responds: Something like that. Our daemons are probably best understood by reference to Unix system daemons, which are programs that run continuously (usually) and handle some particular task; the most popular daemon is the HTTP daemon, or web server. Our daemons are similar: they're objects that hang out and handle some particular function. /daemon/armour manages the armour subsystem, tracking the armour type and armour style definitions; /daemon/weapons manages the weapon subsystem, tracking weapon types, weapon sizes, and ammunition types. These are examples of a class of daemon called broker daemons because their main function is handling definition objects and brokering requests for them; they're mainly found in /daemon. Control daemons are another major class; these live in the ~Project/dmn directories of individual projects, each serving as a central manager for its project. Other daemons just package up some similar functionality, such as /daemon/time; some manage ongoing or specific-purpose processes of the game, such as /daemon/cron, /daemon/autoheal, and /daemon/shutdown.

Two of the universal characteristics of daemons is that they are never cloned and they are never in-game objects. I can conceive of circumstances that could create an arguably legitimate exception to the former, but not the latter.

If you need to refer to a daemon that lives in /daemon in code, you will almost always be using the "service" macros for them, defined in /lib/services.h and its specific-purpose relatives in the /lib/services directory, which look like Daemon_Time, Daemon_Autoheal, Daemon_Shutdown, and so on. Another daemon, /daemon/services, manages these. Besides being prettier than string pathnames, these use a special mechanism to make them faster than other methods you might use for referring to daemons.

Read access privilege: read_lib

Write access privilege: write_lib

/def

This is where system-level definition files reside. Definitions are abstract files that determine certain generic properties of particular files. Races, anatomies, weapon types and damage types are all examples of things that have definitions. This is a good directory to explore to see how the lib is set up.

Read access privilege: read_lib

Write access privilege: write_lib

/etc

A few header files are here, like item.h. This directory is mostly unused and is pretty much on its way out, but the basic idea of it once was that it would container header files that were strongly related to a particular instance of the Ain Soph lib rather than to the core of the lib itself.

Read access privilege: read_lib

Write access privilege: write_lib

/lib

This is the main location for Ain Soph lib header files. Most of the .h files you will ever use are found here. Project header files can usually be found in /d/Almeria/lib, or /d/Affiliations/lib, or something of that sort.

Read access privilege: read_lib

Write access privilege: write_lib

/lib/dev

This is where developer work-in-progress project header files go. It is set up to be writable by ordinary developers. It perpetually is in serious need of cleaning out.

Read access privilege: standard

Write access privilege: standard

/lib/descriptors

This is where the header files that are automatically generated by the descriptor definitions in /def/descriptor are kept. Most header files are manually maintained; these are unusual in being created by the system.

/lib/services

This directory contains header files created by /daemon/services to provide optimized access to "service" functions provided by various system daemons and descriptor definitions. As an example, /lib/services/services_affiliations.h is automatically generated based on information extracted from /daemon/affiliations; it provides macros for addressing /daemon/affiliations itself and for using some service functionality provided by it.

/mod

This hierarchy contains component modules, mainly to be assembled into complete inheritables by things in /std.

Read access privilege: read_lib

Write access privilege: write_lib

/obj

This hierarchy mainly contains files that are intended to be physical objects in the game world; weapons, armour, comestibles, and so on. Files here mostly represent the intersection of lib and content; they are in-game content that's centralized at the lib level rather than belonging to any particular project. There are a few special-case directories under this hierarchy that are used for notably different purposes, however.

Read access privilege: read_lib

Write access privilege: write_lib

/obj/extensions

This is where standard system-wide extension objects are kept. Extensions are a way of loading functionality onto objects using attached, subsidiary objects; for instance, all weapon functionality is tracked by a weapon extension. This allows any object to be treated as an improvised weapon if need be.

/obj/interfaces

System-level input dialog interfaces are kept here. These are objects whose purpose is to handle an interactive dialog; the best example is /obj/interfaces/creation.c, which is the character generation interface.

/obj/master

This is where things like the master object and the simul_efun object are kept -- crucial system things.

Read access privilege: read_secure

Write access privilege: write_secure

/pub

This is a public directory hierarchy where files can be exchanged and freely edited, and so on. One interesting subdirectory is /pub/defunct, where we generally put the /w directories of former developers.

Read access privilege: read

Write access privilege: standard

/std

Contains "final product" inheritable and clonable objects. Most of the objects you will use as base inheritables live here: /std/room, /std/item, /std/autonomon, /std/daemon, and so on.

Read access privilege: read_lib

Write access privilege: write_lib

/sys

Contains "system" header files. Generally, these are distinguished from header files that live in /lib by being more strongly related to things in /obj/master (e.g. /sys/security.h), or by being header files provided with the driver rather than defined by the Ain Soph lib (e.g. /sys/lpctypes.h). Two important, possibly poorly placed header files that live here are /sys/config.h, which contains some important lib-level settings, and /sys/master.h, which defines LS_Foo() macros that are mostly for referring to things in /obj.

Read access privilege: read_lib

Write access privilege: write_lib

/tmp

A public directory for temporary files. Files in this directory are cleared out periodically.

Read access privilege: read

Write access privilege: standard

/txt

Contains text files of various kinds.

Read access privilege: standard

Write access privilege: write_lib

/txt/adm

Contains files that control administrative elements of the system, such as the file that defines what permissions are required to read and write these various directories.

Read access privilege: read_lib

Write access privilege: write_secure

/txt/doc

Developer documentation. Documents retrieved by the 'man' command are pulled from this hierarchy. You should work at becoming familiar with the contents of /txt/doc.

Read access privilege: read

Write access privilege: documentation

/txt/help

Player documentation. This one of the (fairly numerous) places that the 'help' command pulls information from.

Read access privilege: read

Write access privilege: documentation

/txt/log

Standard location for system log files. Many of these are quite interesting.

Read access privilege: standard

Write access privilege: write_lib

/txt/log/dev

Standard location for developer log files. The usual filename convention is /txt/log/dev/<name>.<topic>. Your personal error log file is /txt/log/dev/<your_name>.

Read access privilege: read_w for others' files, standard for your files

Write access privilege: write_w for others' files, standard for your files

/txt/web

The lostsouls.org Web site.

Read access privilege: standard

Write access privilege: write_web

/usr

User files, mainly incarnos and kept-item save files, are in this hierarchy.

Read access privilege: player_files

Write access privilege: player_files

/w

This is where developer workspaces go; your personal directory, /w/yourname, is under this hierarchy. Originally the 'w' stood for 'wizard', back when we used such ill-advised terminology for developers, and the whole 'workspace' thing is just so we don't have to change the directory name.

Read access privilege: read_w

Write access privilege: write_w