Improving Instructions

Information About Open Source Uru & CyanWorlds.com Engine
User avatar
Lyrositor
Member
Posts: 156
Joined: Sun Feb 05, 2012 10:58 pm
Contact:

Improving Instructions

Post by Lyrositor » Fri Mar 02, 2012 3:25 pm

What follows is what I think needs to be improved on the setup instructions for MOSS and the README for CWE. I think it covers about everything I ran into which wasn't due to misinterpretation of instructions on my part. The actual instructions everywhere are quite clear (especially the GoW ones for building the client, save for one point mentioned below in number 8).

MOSS
The following things could be improved, according to me, in the area of MOSS documentation (particularly MOSS/setup).
  • 1. It needs to clearly stated that global_sdl_manager needs to be run AFTER starting the server. I've fixed this already on the wiki, but the main setup instructions still don't indicate it clearly.
  • 2. The different roles of the servers should be quickly but concisely explained, to aid debugging; I myself didn't know what the Gatekeeper server did until a'moaca' explained it to me.
  • 3. A list of files to put under file/Client/External needs to be clearly given. I had a lot of trouble figuring out what to put, since Gehn, Minkata and TOC all used different file sets. I finally settled on the Gehn model since it worked and my client was the H'uru client. However, this list would probably depend on whether the client is from H'uru or OpenUru.org.
  • 4. It should be stated that it's normal for MOSS not to find SecurePreloader.mbm when connecting with an H'uru client (I don't know if this should be written under MOSS or CWE, since CWE is creating the "problem" but MOSS is reacting to it).
  • 5. Manifest Creator creates the manifest from a current client installation. It would thus be best if it was pointed to an already working client setup for this shard, instead of the default Uru Live install (this will automatically gzip the appropriate clients). Maybe this should be made clearer?
  • 6. The files to be renamed and moved around should be explicitly named; I guessed at it, since the filenames are pretty self-explanatory.
CWE (general)
The following corrections I'm suggesting seem to apply to every fork of the CWE client.
  • 1. The AuthFiles used (Python and SDL) shoudn't come from AuthFiles.zip (reference purpose should be explicitly stated under MOSS/Setup, for example), but instead should be compiled each time from the appropriate repository (H'uru, OpenUru.org...).
  • 2. Standard versions of PhysX, DirectX and Visual Studio Redistributable have to be established. I ran into problems during installation because one of the installers (I think it was dxwebsetup.exe) refused to install because a newer version was already installed. I'm not sure if the GoW and OU are using the same versions of these installers, but if they aren't, I think it might be to their advantage to determine the "reference" installers, and provide direct links to those files.
  • 3. Maybe a clear guide on licensing? I wasn't completely sure of what to put, so I kept all the COPYING files everywhere, for example. Must these be made available somewhere? The responsbilities of a shard owner should be more clearly outlined, in my opinion (MOSS/Setup has a few things to say on the subject, but I'm not sure it covers everything). In my case, I hoped I'd done everything right, but just re-reading those instructions has shown me I need to link to the actual changeset of the repository I used. Oops. :oops:
H'uru CWE
Finally, this is just for the H'uru fork of CWE.
  • 1. The old python27 branch should be removed, and the section "Running Instructions" needs to be updated in the README.
  • 2. It should be made clear that the "-LocalData" trick doesn't work for the External client. This had me stuck a long time, until I took a peek at the source code.
  • 3. The new SecurePreloader mechanism should be explained, and the fact that it still allows for backward-compatibility. Maybe this should be in the README, or maybe in a separate MOSS<->H'uru CWE article.
  • 4. Is there a difference between /LocalData and -LocalData? I only tried the latter, but in several places, I have seen /LocalData stated instead.
  • 5. It needs to be specified that server.ini HAS to be encrypted for the external client, but NOT for the internal client.
  • 6. server.ini seems to use the standard MOULa generators for the keys it uses. Maybe it should be explicitly written somewhere that, when converting keys from MOSS for example, the converted keys need to use the appropriate encryption. Or, alternatively, the encryption option could be coded into server.ini.
  • 7. How far is this issue from being closed? Everything worked fine for me (but I only built the client)...
  • 8. When I first built the client, everything went fine. But I guess I installed other DirectX stuff later because eventually, I had to manually specify the locations of the DirectX files.
I hope I didn't forget anything. 8-)
Lyrositor
Explorer #16601888
To D'ni, or not to D'ni. There is no question.
Image

User avatar
Luna
Member
Posts: 11
Joined: Sat Apr 09, 2011 2:37 pm

Re: Improving Instructions

Post by Luna » Fri Mar 02, 2012 3:43 pm

I have a few comments on your list, I think some things would be kind of overdone

/LocalData is the same as -LocalData. It's simply a matter of what syntax you prefer. Also for it not working with an external client, think of it this way. Do you want any user to be able to run a client with locally modified files? No, you don't so you disable that :P Same thing for the server.ini, do you want everyone to be able to read the server IP?

As I understood it the SecurePreloader thing gave you a warning, under programmers it is rather accepted to ignore warnings(which is why compiling the client gives a huge amount of warnings). Warnings are usually not critical.

User avatar
Lyrositor
Member
Posts: 156
Joined: Sun Feb 05, 2012 10:58 pm
Contact:

Re: Improving Instructions

Post by Lyrositor » Fri Mar 02, 2012 4:19 pm

Luna wrote:/LocalData is the same as -LocalData. It's simply a matter of what syntax you prefer.
Thanks for clearing that up! :)
Luna wrote:Also for it not working with an external client, think of it this way. Do you want any user to be able to run a client with locally modified files? No, you don't so you disable that :P Same thing for the server.ini, do you want everyone to be able to read the server IP?
I didn't ask for this feature to be implemented, I just said, I think it should be made clear that it doesn't exist in the External client. Anyway, the IP can be read by anyone with Wireshark, for example. And I'm not saying it shouldn't be encrypted, I'm saying it should be specified that it needs to be encrypted for the External client to work.
Luna wrote:As I understood it the SecurePreloader thing gave you a warning, under programmers it is rather accepted to ignore warnings(which is why compiling the client gives a huge amount of warnings). Warnings are usually not critical.
I agree! But shouldn't the user be at least informed why it's appearing, which will allow the documentation to make a link with what's going on in the H'uru client.
Lyrositor
Explorer #16601888
To D'ni, or not to D'ni. There is no question.
Image

User avatar
JWPlatt
Member
Posts: 1097
Joined: Sun Dec 07, 2008 7:32 pm
Location: Everywhere, all at once

Re: Improving Instructions

Post by JWPlatt » Fri Mar 02, 2012 4:53 pm

Excellent. This is a great contribution because it's from the point of view of someone just getting started and its a tangible solution for the problems you encountered. People exactly like you need to be the majority case for a very long while to build on the success of open source, and we must accommodate it. From nothing to an open shard in a short time is a real accomplishment. Okay, so not to put too fine a point on it, but can you also help us understand which instructions were fine, but were not followed correctly? It's still possible that those instructions should could some with a caution against skipping, made clearer for the beginner, or formatted so they are not so easily missed, for example. In other words, a post-mortem on your process from a documentation point of view besides what was actually missing.
Perfect speed is being there.

Deledrius
Member
Posts: 95
Joined: Sun Dec 28, 2008 6:29 pm

Re: Improving Instructions

Post by Deledrius » Fri Mar 02, 2012 4:55 pm

For CWE#7 - AFAIK everything's been converted at this point except a few small projects of questionable utility outside of use by Cyan, either because they are specific to their unique build system and therefore of little interest, or else have been superseded by newer code either elsewhere in CWE or by non-CWE projects.

User avatar
Lyrositor
Member
Posts: 156
Joined: Sun Feb 05, 2012 10:58 pm
Contact:

Re: Improving Instructions

Post by Lyrositor » Fri Mar 02, 2012 5:08 pm

JWPlatt wrote:Okay, so not to put too fine a point on it, but can you also help us understand which instructions were fine, but were not followed correctly? It's still possible that those instructions should could some with a caution against skipping, made clearer for the beginner, or formatted so they are not so easily missed, for example. In other words, a post-mortem on your process from a documentation point of view besides what was actually missing.
I'll start working on that this minute! ;)
Lyrositor
Explorer #16601888
To D'ni, or not to D'ni. There is no question.
Image

User avatar
Lyrositor
Member
Posts: 156
Joined: Sun Feb 05, 2012 10:58 pm
Contact:

Re: Improving Instructions

Post by Lyrositor » Fri Mar 02, 2012 5:31 pm

Okay, here we go. What follows is a chronological list of every problem I ran into while setting up MOSS and CWE (from what I can recall of my abysmal memory).
  • Confusion about where MOSS is installed. The installation intructions (being general) didn't specify anything else than "prefix". Finally found it under /usr/local on Ubuntu 10.04.4. Changed it to ~/moss.
  • global_sdl_manager needed to be run after installation. Found a previous thread which answered my questions. Now added to the wiki, so already fixed.
  • Not understanding exactly what the whole manifests did, since the installation assume you know what a manifest is. Now, I do.
  • Looked a long time for an Express edition for VS2003. No such thing :(
  • Starting server twice by accident gave me error messages (see Installing MOSS thread). Finally understood by looking at running processes.
  • Needed to add MOULSCRIPTS to my internal client for it to work.
  • Problems with keys, but this can't be fixed by clearer instructions. I was just not accurately keeping track of where I put them.
  • Had to edit my manifest files for my client. Not specified in the instructions.
  • Initially skipped the renaming and moving of files, didn't think it was important. My bad.
  • Various account creation problems since I din't understand the distinction between all the encryption algorithms.
  • My MOSSi script had various problems... Mostly due to syntaxical errors on my part.
  • Couldn't compile Wireshark with plugin. Various error messages.
  • Didn't realize I had to encrypt anything until I looked at instructions on the GoW fort a DIRTSAND/CWE setup.
  • Debug couldn't run. No idea why.
  • Hadn't found a way to "port" my keys from MOSS to H'uru clients. Finally, one member (don't remember which thread or which member) pointed me in the way of the right gool for conversion.
  • psql problems, but that's PostgreSQL's problem and not MOSS' or H'uru's.
Actually, now that I think about it, some of those were kind of due to lack of documentation because it assumed existing technical knowledge before.
Lyrositor
Explorer #16601888
To D'ni, or not to D'ni. There is no question.
Image

User avatar
JWPlatt
Member
Posts: 1097
Joined: Sun Dec 07, 2008 7:32 pm
Location: Everywhere, all at once

Re: Improving Instructions

Post by JWPlatt » Fri Mar 02, 2012 6:17 pm

Wow, you're hired! This really is an impressive thing you've done sharing all this - and so quickly. I think it's obvious that whatever it is you want to do, you want to finish what you start and you want to do it well.

My LOL moment, because I can so identify with this kind of understatement:
Lyrositor wrote:Now, I do.
Maybe for one of your Q&As:

Q: What the heck is a 'manifest' and why should I care?

Thank you!
Perfect speed is being there.

Deledrius
Member
Posts: 95
Joined: Sun Dec 28, 2008 6:29 pm

Re: Improving Instructions

Post by Deledrius » Fri Mar 02, 2012 6:32 pm

Indeed, this is an excellent and coherent listing. Good work!

It's one thing to have difficulty, it's quite another to be able to detail why, and how to avoid it in the future.

User avatar
Lyrositor
Member
Posts: 156
Joined: Sun Feb 05, 2012 10:58 pm
Contact:

Re: Improving Instructions

Post by Lyrositor » Sat Mar 03, 2012 1:19 am

Thank you everyone for your praise! :D I'm happy you like my work. I'm not done yet, though. Starting tomorrow, I'm going to begin building the MOSS/FAQ that was previously requested, using my errors as a basis for helping others who, like me, might encounter these errors. :?
Any suggestions, or special requests? Should I include a section "Clients" which explains special steps to take for the various clients out there?

EDIT: I've also been thinking. :idea: Would an event hosted in the OpenUru.org hood/on Minkata help? Like a sort of MOSS install party, in which I share my hard-earned "wisdom" with my fellow explorers? Similar to the Q&A there was some time ago.
Lyrositor
Explorer #16601888
To D'ni, or not to D'ni. There is no question.
Image

Post Reply

Return to “Information”

Who is online

Users browsing this forum: No registered users and 1 guest