It seems that the quality of readme.txt files has become quite bad. Sometimes a zipped map file doesn’t even contain one!
Dougjp recently sent me an email which discusses the read me files in map downloads. He’s a quote:
“This was brought to light recently with a HL2 map which could not be played based on all common sense guessing…. This is based on the fact that once a map or mod is released to the public, all recipients are not mappers ;)”
I agree with him, sometimes it can be really difficult to work out what to do with a file/folder once you have downloaded it, especially if you are new to gaming!
As you can imagine I’ve downloaded a LOT of maps and mods, and the quality of readme.txt files varies from almost useless to fantastic. I remember there used to be a template available but lately I haven’t seen any read mes based on it.
I propose that we create a new template. Below is my starting draft of headings. After a little discussion I will create a text file and make it available for download, but to be honest it isn’t exactly hard to create a fresh one from the list! Anyway, here my starting list:
- Title:
- Filename:
- File Version:
- Released Date:
- Game:
- Game Version:
- Author:
- Author Website:
- Author Email:
- Description:
- Story:
- Installation Instructions:
- Load/Run Instructions:
- Gametype:
- Difficulty Settings:
- Known Bugs:
- Development Notes: (Compile timne etc)
- Previous File Versions:
- Beta Testers:
- Credits:
- Other Maps by the Author:
- E.U.L.A. (Permissions etc)
- Disclaimer – Should this be part of the E.U.L.A.?
- Final Notes:
When I received Dougjp’s email it also made me think about how it would be useful if filenames were standardized. I don’t want to limit creativity, just make it easier for people like you and me to know what we are downloading!
There was a time when I used to download Unreal Tournament files, not just SP maps but all gametypes. Often then would have prefixes that made it clear what type of map you were downloading. Things like DM-house.zip, CTF-house.zip and AS-house.zip.
I don’t see why that couldn’t be extended to all games? Of course this would require a community effort and agreement, which is probably almost impossible. If a few of the big sites got together and a agreed a format (After consultation with the community!) then everybody would benefit.
I propose we start the process now. Being the Know it all, here are a few ideas! I suggest that the name starts with a three or four letter code for the game. Something like:
HL2, followed by a hyphen. Next comes the gametype, again with an agreed code, another hyphen then the map/mod name (limited to 10 characters) and another hyphen. Then comes the version: 1.1, hyphen, next the language: eng. hyphen once more and lastly the date released, using three letters for the date to avoid confusion!
Here’s an example:
hl2-sp-house-1.2-eng-13oct06.zip
Not exactly the shortest filename but probably more useful than some of the crappy readme.txt files that I’ve seen!
What are your thoughts?
Thanks to Dougjp for the post idea.
Going out on a tangent, why not turn it all around. Rather than have the mappers/users responsible for this, why not make the game capable of doing all of this for you? Sort of like ID3 tags for MP3 files. A game has some data hardcoded into it (e.g. author, notes etc). Of course, the instillation readme would still have to be present but 9 times out of 10, that’s the only bit I look at. I know steam do this and quite well for mods, but it is definitely something that could be expanded upon.
That could work! Maybe it should be built into the map data and then extracted. But of course that’s only for Steam game.
Something uber strange has just happened. A comment on the The Challenge post directed me to a new mod. The filename is:
HL2SP_MrDeathwish_part01_v1.0.exe
Which just goes to show that some people can do things properly!
It’s not exactly as my draft is but it’s certainly better than most filenames!
BTW, do you think I should rename ALL the files before I upload them? I decided not to do this becasue often people search for a particualr filename but it might be a good thing to do?
if I download something called ironstorm or whatever it maybe called I like the mod to have the name first so I know where the hell to look.i have gigs upon gigs of mods and half of the names are no where near the name of the mod.
i should refrase that. mr murder was a good mod to download then find in my folder since I knew it started with the hl2 stuff.its the others that start with numbers or whatever that tick me off. eg:return to xen I believe is called gargent.zip. now how would I even think of looking in g for that.
can’t edit so murder = deathwish
Okay. so you are agreeing with me? Sorry, I’m a little confused.
What are your thoughts about the read me file?
Also you should be able to edit your own comment, assuming you are logged in.
yes I agree with you names should reflect what they are.i was a little confused myself lol.as for thr read mes yes most of them do need to be done better or at least add one to the file.i also have found many that are in japanese,chech,french etc with no english section making it very hard to understand.
many years ago I did find a sof2 read me txt file, and from then on I always use that one, just changing every time all the info. I agree, that there are horrible tx file going around. still, I do have to say, that even when you add one to your zip/rar file it happens a whole lot of times that people mail me with questions that are all asnwered in the read me txt file. (but lets asume that that are noob custom map players). but for those who don’t know how to make one it would be a good idea to have one here on line that they can use.
leon
a smart thing to do in your txt file is always to give credit to the company that made the game.
That’s why my draft above includes a CREDITS: section. 🙂
I agree with the general structure which you are proposing, but I have a couple of suggestions.
1. explain what the “File Version” means. Very few people will know how to include a correct file version. First number = Major release. Second number = Bug fixes (the third number is not really necessary).
2. There should be an E.U.L.A included at the end just for legal reasons.
I also agree with your idea about how to name a file, but I don’t think that including the date will be necessary because you already have the file version (which is the most important thing).
i’m sorry Phillip, didn’t see that part, overlooked it I gess.
leon
No need to apologise. You are right to point out that people should credit the game makers and not just the people who helped them.
Peter, you point about the file version is true but don’t you think it’s beyond the scope of the read me? But that does remind me that perhaps the read me should include the changes from previous versions.
For example:
1.0: Full Release
0.9: Added new enemy in basement
0.8: Corrected lighing issue in attic
The E.U.L.A. is also a good additions. I wonder if there are any specifically for custom created maps and mods?
I’ve edited the draft based on the above.
I know what you mean about the date but I added it because I felt it would somehow be really useful. I do accept that it is probably not needed.
OH, I just remembered something else. I reently opened a readme and it contained detailed information about the technical aspects. Things like construction time, compile time etc. DO we think that should be included?
yes, that I think is very usefull info, maybe not for some people but for other mapper/modders it can be usefull. here is an example of for instance the latest cdo2 sp-map’s read me txt that I released, (have deleted the info, it shows only the things that we are talking about);
* Construction *
Buildtime
Compile Time
Editor
Map Known Bugs
New Textures?
New Sounds?
Custom Soundtrack?
Compile Machine
* Permissions*
All original and composed textures or assets in this level remain property of
the sources respective owners.
You MAY distribute this ZIP,PK3 in any not-for-profit electronic format (BBS, Internet,
CD, etc) as long as you contact me first, and include all files, including this readme, intact in
the original archive.
===========================================================================
* Warning – Must Read and Understand Before Use*
The author of this file accepts no responsibility for damage to data, or physical damage
to hardware, caused by the appropriate or inappropriate use of this file. It is deemed
that users who run this file, automatically are considered as having read and understood
this liability clause before using the said file.
===========================================================================
Leon I have edited some of your list because they were already in the draft – Phillip
Good point about the new elements (Textures sounds etc) I’ll add those.
The permission and warning section would probably be covered in the EULA.