Maxis Documentation - Comments
@SimGuruEugi – since you said here that you’d look into updating the docmentation PDF, here’s some more suggestions I thought I should post – perhaps you can take a look at that too while you’re at it:
– A table of contents and/or index would make that PDF quite a bit easier to use I think, particularly since you are often using slightly different terms than the ones that have been established in the modding community over the years (which makes it difficult to know the correct search terms when trying to just search the PDF).
– String localisation (page 11, middle): A list of which top byte corresponds to which language would be very helpful; could you perhaps add that? You state “The string table system will not be discussed more here, as it a fairly straightforward system and works similarly to previous Sims games” but there are quite many TS4 modders who have no previous experience with earlier games.
– I think there is no explicit mention of when/why to use decimal vs. hexadecimal references in XML tuning, which has been confusing lots of people (me included =P) – a short mention like “note that in XML tuning, references to other resources are given in decimal form” might be helpful.
– Naming conventions (when to use or not to use a custom group ID, how to generate resource keys from a hash etc): this is currently found in various places throughout the document (page 4 top, page 17, examples throughout the entire documnt) – since this is very important for all sorts of custom content, not just XML tuning and scripting, maybe this could be grouped together some more? E.g. on page 4 you just state "ALWAYS use a hash for the instance": people who don’t know what a hash is will be quite lost at this point. If the examples and explanations you're giving later on (e.g. page 5: "In particular, the resource type is the 32-bit FNV-1 hash of this instance type. As an example, the resource type of “topic” is 0x738e6c56. More on FNV-1: http://www.isthe.com/chongo/tech/comp/fnv/index.html") were added in here I think this would be much easier to understand.
– Also, "Set the top bit of the group to 1 for all resources" or "Just generate the 64 bit hash and then force the top bit to 1" (page 3/4) is something that goes over the head of a lot of people – it would be great if, early on in the PDF, some kind of simplified explanation for this procedure could be added. For example: "Use a group ID of 0x80000000 for all custom content except XML tuning (i.e. set the top bit to 1)", and/or “to make sure that custom content resources will never have the same ID as Maxis resources (and thus accidentially override Maxis content), please always use an instance key that is higher than 0x8000000000000000 (i.e. set the top bit to 1)" or something along these lines. When people understand better what they're doing and why they need to do it, that works better than blindly following rules IMO =).
– Direct links to the modding forum (not just the main Sims 4 forum as the modding forum is not visible in the overview for people who are not already logged in!), the actual download thread of the PDF/documentation, and perhaps even the various .bt files and other resources that you have posted meanwhile might also be useful.
– A table of contents and/or index would make that PDF quite a bit easier to use I think, particularly since you are often using slightly different terms than the ones that have been established in the modding community over the years (which makes it difficult to know the correct search terms when trying to just search the PDF).
– String localisation (page 11, middle): A list of which top byte corresponds to which language would be very helpful; could you perhaps add that? You state “The string table system will not be discussed more here, as it a fairly straightforward system and works similarly to previous Sims games” but there are quite many TS4 modders who have no previous experience with earlier games.
– I think there is no explicit mention of when/why to use decimal vs. hexadecimal references in XML tuning, which has been confusing lots of people (me included =P) – a short mention like “note that in XML tuning, references to other resources are given in decimal form” might be helpful.
– Naming conventions (when to use or not to use a custom group ID, how to generate resource keys from a hash etc): this is currently found in various places throughout the document (page 4 top, page 17, examples throughout the entire documnt) – since this is very important for all sorts of custom content, not just XML tuning and scripting, maybe this could be grouped together some more? E.g. on page 4 you just state "ALWAYS use a hash for the instance": people who don’t know what a hash is will be quite lost at this point. If the examples and explanations you're giving later on (e.g. page 5: "In particular, the resource type is the 32-bit FNV-1 hash of this instance type. As an example, the resource type of “topic” is 0x738e6c56. More on FNV-1: http://www.isthe.com/chongo/tech/comp/fnv/index.html") were added in here I think this would be much easier to understand.
– Also, "Set the top bit of the group to 1 for all resources" or "Just generate the 64 bit hash and then force the top bit to 1" (page 3/4) is something that goes over the head of a lot of people – it would be great if, early on in the PDF, some kind of simplified explanation for this procedure could be added. For example: "Use a group ID of 0x80000000 for all custom content except XML tuning (i.e. set the top bit to 1)", and/or “to make sure that custom content resources will never have the same ID as Maxis resources (and thus accidentially override Maxis content), please always use an instance key that is higher than 0x8000000000000000 (i.e. set the top bit to 1)" or something along these lines. When people understand better what they're doing and why they need to do it, that works better than blindly following rules IMO =).
– Direct links to the modding forum (not just the main Sims 4 forum as the modding forum is not visible in the overview for people who are not already logged in!), the actual download thread of the PDF/documentation, and perhaps even the various .bt files and other resources that you have posted meanwhile might also be useful.
