Please help strengthen our documentation by rating items on how helpful they are, and by suggesting documentation, that we are missing and should focus on next.
posted on 20:36 - 13 May 2010 | posted by Lev
last modified on 19:38 - 18 May 2010 | last modified by Lev
First of all, you should have a good understanding of how it is that the generator creates works, before you start building on it.
How the generator works
The generator works by loading up data files and then connecting the references together to result with a unique member. All data files are stored within DIR_LIB/generator/. If you are on a standard installation, this is lib/generator/.
Each line in each data file contains a separate reference or element, and each parameter for that respective element is separated by a vertical bar, like this: |
Here is an example element from the rolls.cfg file:
n=Samantha|s=f|e=c,a
This element contains 3 parameters (n, s and e). Each element only needs to contain a single parameter, which depends on the context of where the element is stored.
- If the element is stored in rolls.cfg it should have at least the n (name) parameter.
- If the element is stored in profiles.cfg it should have at least the p (profile introduction) parameter.
- If the element is an avatar image stored in the avatars directory it should at least have the s (sex) parameter.
As you can see above, unlike the data files such as rolls.cfg and profiles.cfg, avatars are image files stored within the avatars directory. Each image in this directory is an element in the same way that each line in rolls.cfg and profiles.cfg are elements.
So while each element must have one parameters they may also contain any number of extra parameters. The parameters available are:
- a = age
- b = beauty (not used yet, but some elements will refer to this)
- c = country
- cc = crop coordinates (only works with avatars; not used with rolls or profiles)
- e = ethnicity
- n = name
- o = obscenity (not used yet)
- p = profile introduction (should only be used in profiles.cfg)
- s = sex
Every parameter may also be placed alongside any element, and each parameter (except p - profile introduction) may have more than one value. If you wish to assign more than one value to a parameter you should separate it with a comma. For example:
s=m,f
This means that the element can be used for males or females. When assigning multiple integer values to a parameter, a range is interpreted. For example:
a=16,30
This means the age may be between 16 and 30 ; *NOT* 16 "or" 30.
Please note that the cc parameter (crop coordinates) doesn't use a range even though it contains integer values.
How avatar parameter values are stored
Since avatar elements are image files, their parameters are not stored anywhere in a file like, rolls.cfg and profiles.cfg. Instead their parameters are stored within the file's name itself, by writing the parameter key before a pair of parenthesis, which contain the parameter values. Here's an example avatar file name:
s(f)a(13,19)e(c)cc(0,80,400,480).jpg
This image can be used as an avatar for female members, aged between 13 and 19, and whom are Caucasian.
The cc parameter, though not necessary, tells Theia how to crop the image for use as an avatar. The crop coordinates should be 4 integers: x1, y1, x2 and y2. If the crop coordinates are provided, Theia will automatically crop the image from the specified coordinates. You can determine an image's pixel coordinates by hovering your mouse over it in most image manipulation programs. If the crop coordinates are not provided then the whole image area will be used as the avatar.
Avoiding avatar naming conflicts
Lets assume you create a huge database of avatars, many of which should be applied to the same type of people. Since only one file can have a specific file name in the same directory, just scribble anything additional onto the file's name to make it unique. So if we had another image for Caucasian females, aged 13 through 19, we could name it:
s(f)a(13,19)e(c)cc(0,80,400,480)-2.jpg
Notice the added -2 at the end of the file name. You can write anything there to keep it unique, and it doesn't even need to be at the end of the file name, but is suggested.
How it all comes together
When generation commences, it all begins with whatever is selected at the top of "generation priority order". Let's assume the priority is set to the default order, which is:
- avatars
- profiles
- rolls
The generator will now run through all avatar images looking for matches to the requirements specified in the demographic. Suppose we said we want to generate female members aged between 20 and 40. The generator will now pick out avatars that are flagged to meet those requirements, and then it will move along to the profile elements, while discriminating even more based on the new parameters it picked up from the avatar elements, and then finally it will move onto the roll elements using all the parameters it picked up from avatars and profiles. The end result is an array of data composed of parameters it picked up from your requirements and all 3 phases of scanning.
Let's suppose this hypothetical scenario:
You want to generate a female member aged between 20 and 40 years old, and use the default priority ordering.
As the generator starts scanning the avatars it comes across this avatar image, which meets the specified requirements:
s(f)a(20,25)e(c,ee)cc(0,80,400,480).jpg
Now, the scanning goes onto profile elements, but now it will only allow a match when these conditions are met:
- female
- aged 20-25
- Caucasian or Eastern European
So now the generator has found this profile reference, which matches the requirements:
p=I'm just your average girl|s=f
Since the p parameter should only be contained within profiles.cfg, no other requirements are added here, so the same requirements are used for scanning the rolls, which matches this element:
n=Sally|s=f|e=c
The end result is a unique member named Sally, who will be between 20 and 25 years old and living in one of the countries associated with the c (Caucasian) ethnicity, as listed in ethnicities.cfg!
Defining the available sexes
The default sexes.cfg file contains only two sexes: male & female. The value of the s parameter is the sex identifier which will be used in the avatars, rolls.cfg and profiles.cfg. The sName parameter (used solely in this file) denotes a textual, human-readable, name which will be displayed when using the generator.
Here is how it looks:
s=m|sName=Male
s=f|sName=Female
s=f|sName=Female
But let's say you have a site which needs to use a "transexual" or "transgender" sex as well. Then your sexes.cfg file could look like this:
s=m|sName=Male
s=f|sName=Female
s=t|sName=Transgender
s=f|sName=Female
s=t|sName=Transgender
You do not need to use any of the predefined sexes, but your other data files should reflect those which are defined here.
Defining the available ethnicities
The ethnicities (stored in ethnicities.cfg) are defined in the same way that sexes are defined, though eName is used instead of sName, and an additional parameter (c) is used to define countries for that ethnicity.
Here is how the ethnicities.cfg file could look:
e=c|eName=Caucasian|c=US,CA,GB,FR,SE,CH,NL,DE,FI,AU,AT
e=l|eName=Latin|c=CO,CL,CU,EC,MX,US
e=me|eName=Mid-East|c=EG,JO,KZ,SA,KW
e=as|eName=Asian|c=HK,JP,NP,TW,TH,VN,PH,US,CA
e=a|eName=African|c=ZM,ZW,TZ,US,CA
e=ee|eName=Eastern European|c=MK
e=l|eName=Latin|c=CO,CL,CU,EC,MX,US
e=me|eName=Mid-East|c=EG,JO,KZ,SA,KW
e=as|eName=Asian|c=HK,JP,NP,TW,TH,VN,PH,US,CA
e=a|eName=African|c=ZM,ZW,TZ,US,CA
e=ee|eName=Eastern European|c=MK
Notice how the countries are declared by their 2 character code. Here, Caucasian is defined as someone who lives in the USA, Canada, Great Britain, France, Sweden, Switzerland, The Netherlands, Germany, Finland, Australia and Austria. To determine a countries 2 character code, just load up the "countries" module file in the "manage words and phrases" tool (admin tool 219).
You do not need to use any of the predefined ethnicities, but your other data files should reflect those which are defined here.
Bookmark item @
