Official(?) MT 1.3 Documentation Project

Doc requests, organization, and submissions

Moderators: dorpond, trevor, Azhrei

Post Reply
Gamerdude
Cave Troll
Posts: 89
Joined: Thu Feb 04, 2010 12:17 am

Official(?) MT 1.3 Documentation Project

Post by Gamerdude »

Well, based on a discussion in another topic area ( What's Wrong with this Video Tutorial?) Here is the first draft of my proposed outline for a complete 'book' on MT. This outline is based on the topics and information in the Maptools online documentations at http://lmwcs.com/rptools/wiki/Main_Page and videos at http://www.rptoolstutorials.net/All comments good and bad are welcome.

CHAPTERS are in X. BOLD ITALICS
CHAPTER SECTIONS are in X.Y ITALICS
SUB SECTIONS are in X.Y.Z NORMAL

Chap 1. What is MapTools?
[EDIT 01/18/11]: A summary of Maptool. Ie, what you have to have to get any game going, but not any specific game system. A list of minimal features, followed by optional features.[/EDIT]

Chap 2. MapTool Windows & Objects
2.1 Maps
2.2 Tokens
2.3 Macros
2.4 Forms

Chap 3. Getting Maptools Started
3.1 Downloading & Installing
3.2 Java Memory Settings
3.3 MapTool Preferences
3.4 Connecting Computers
--- 3.4.1 Starting a Server
--- 3.4.2 Finding & Connecting to a Server
3.5 Campaign Repositories
3.6 Resources

Chap 4. Maps
4.1 Layers
4.2 Images
4.3 The Drawing Tools
4.4 Everything Tokens
--- 4.4.1 Token Basics
--- 4.4.2 Token Types
--- 4.4.3 Token Properties and Manipulation
4.5 Vision, Lighting, and Fog Of War (FoW)
--- 4.5.1 FoW
--- 4.5.2 Vision Blocking
--- 4.5.3 Lights and Sights

Chap 5. Text Chat
5.1 Text Chat Formatting
5.2 Dice Expressions in Chat
5.3 Roll Formatting Options
5.4 Roll Visibility Options

Chap 6. Dialogs, Frames, and Forms[Edit 01/20/11]
6.1 The difference in Dialogs, Frames, and Forms
6.2 Dialog & Frame Design
6.3 Form Design
6.- Tables (.mttables)

Chap 7. Macros
7.1 What Can a Macro do for you?
7.2 Creating Macros, In The Begining
7.3 Decisions in a Macro
7.4 Doing Repetitive Things with a Macro
7.5 Variables the Types and the Special


Appendix A: Glossary
Appendix B: Shortcut Keys
Appendix C: Chat & Dice Commands
Appendix D: Macro Technical Reference

[EDIT 01/18/11] from input by jfrazierj. Changes in titles on input from Azhrei
[EDIT 01/19/11] Added Chapter/Section/Subsection numbering
[Edit 01/20/11] zEal input on forms
Last edited by Gamerdude on Thu Jan 20, 2011 6:10 pm, edited 8 times in total.
Al B. USAF RET.
*Chief Organizer and Bottle Washer - 'User Creations' Forum*

MT Framework Directory **LISTING** (UPDT 2012-02-10)

User avatar
CoveredInFish
Demigod
Posts: 3104
Joined: Mon Jun 29, 2009 10:37 am
Location: Germany
Contact:

Re: Official(?) MT 1.3 Documentation Project

Post by CoveredInFish »

This looks very promising.

One question comes to my mind though: what exactly do you call forms?

If its really html forms in maptool frames/dialogs then I wonder about their prominent position. It would be more of a subchapter of macro writing.

User avatar
jfrazierjr
Deity
Posts: 5176
Joined: Tue Sep 11, 2007 7:31 pm

Re: Official(?) MT 1.3 Documentation Project

Post by jfrazierjr »

I would suggest in your overview that you come up with some type of summary of Maptool. Ie, what you have to have to get a game going, not counting any game specific documentation. Perhaps even a list of minimal features, followed by optional features.

Ie,
  • Java 1.6 or higher on Windows, *nix, or Mac OS 10.x
  • For Internet play, you will need to set up and start a server, which may(or may not) include making changes to your internet router or gateway device.
  • one or more images, either png or jpeg to represent enemies and player characters
  • Thats it! If you are lucky and your router/internet connection device is already set up properly, you could be playing a game with others in as little as 5 minutes.

However, there are far more advanced features which may be(but are NOT required) which you can add to your games as you see fit such as
  • Simple dice rolls, plus the ability to save simple dice rolls to individually labeled macro buttons
  • Square, Hex(either horizontal and vertical), or Gridless grid on a per map basis.
  • Vision, either Circle, Square, or Conic with ranges and (and for Conic, arcs)c) arcs defined by the GM.
  • GM defined Lights, including Circle, Square, or Conic with ranges (and for Conic, arcs) defined by the GM.
  • Additionally, Vision can be set to Off, Daytime, or Nighttime(thus requiring light sources to see) on a per map basis
  • Vision blocking such as walls, etc which may be defined by the GM
  • Advanced macros which include the ability to alter a characters properties(such as add/remove damage), move a token(this is what the images used to represent a player's character or an enemy is called), etc
  • ...more stuff that Maptool can do here
The above features are all optional. You can use and few or as many as you wish to use(of course, some features depend on the use of other features, such as Vision blocking depending on the use of Vision to work.) Additionally, in most cases, you can add features one at a time as you feel comfortable with the configuration and concepts to get it working for your game system.

Of course, this is a overly simplified list, but the first thing "some" people say when they look at Maptool is "wow, this is hard.. I have to be a programmer to use Maptool", and this should be addressed right from the start, as early into their MapTool career as possible. Ie, the simplest possible play would be just like any other internet sharing white board application.
I save all my Campaign Files to DropBox. Not only can I access a campaign file from pretty much any OS that will run Maptool(Win,OSX, linux), but each file is versioned, so if something goes crazy wild, I can always roll back to a previous version of the same file.

Get your Dropbox 2GB via my referral link, and as a bonus, I get an extra 250 MB of space. Even if you don't don't use my link, I still enthusiastically recommend Dropbox..

Gamerdude
Cave Troll
Posts: 89
Joined: Thu Feb 04, 2010 12:17 am

Re: Official(?) MT 1.3 Documentation Project

Post by Gamerdude »

CoveredInFish wrote:This looks very promising.
Thank you. Nice to know the first tentative step appears to be in the right direction. ("That's one small step for maps, One giant leap for MapTools"!)
CoveredInFish wrote:One question comes to my mind though: what exactly do you call forms? If its really html forms in maptool frames/dialogs then I wonder about their prominent position. It would be more of a subchapter of macro writing.
You are correct on what I say are "forms", and I agree with your thinking to a point but let me explain my thinking.

Macros are used everywhere, not just in forms, and are a huge topic all by themselves. Forms in MapTools are a special container, an interface element that can utilize macros but don't have to. Think of a form as a car, and macros as the engine, electrical system and such. Without them you can design how a car looks, how pieces move around, turn knobs and push buttons. You can make an ugly car nobody will want to get into or a very nice looking car that everyone will want.

Now bring in the macros: give the car an engine, an electrical system, brakes etc. Whether you have the ugly car or the nice looking car, it does things. I have had whole textbooks on just UI design as well as having it covered in systems analysis and design books as a separate topic.

But you also put a little point in my head that I will need to remember: since forms and macros are closely associated I have to watch out for putting too much teaching about macros in the forms section and confusing the two topics.

Part of my computing/teaching background is "User Interface Design". Mocking up for feedback, how the back end (macros) affects the front end (form) and the front affects the back.
jfrazierjr wrote:I would suggest in your overview that you come up with some type of summary of Maptool. Ie, what you have to have to get a game going, not counting any game specific documentation. Perhaps even a list of minimal features, followed by optional features.
Good point, I've edited it and included it in the original post above!

Thanks! Keep the good ideas coming.
Last edited by Gamerdude on Tue Jan 18, 2011 3:21 pm, edited 1 time in total.
Al B. USAF RET.
*Chief Organizer and Bottle Washer - 'User Creations' Forum*

MT Framework Directory **LISTING** (UPDT 2012-02-10)

User avatar
Azhrei
Site Admin
Posts: 12086
Joined: Mon Jun 12, 2006 1:20 pm
Location: Tampa, FL

Re: Official(?) MT 1.3 Documentation Project

Post by Azhrei »

That looks like a good start, GD.

In general, I'd stay away from using "Overview" or "Introduction" too many times. Instead, put the introductory information at the front of the chapter and the more advanced stuff later. That makes it much easier to reference later on and keeps all information together. Sometimes the advanced sections may have to reference material that isn't covered yet, but that's okay because it's "advanced" and will likely be skipped the first time the user reads the document. For example, I don't think anyone uses "Roll Visibility Options" (under Text Chat) when typing in commands in the chat window. Instead, they are almost exclusively the purview of macros. They should still stay under Text Chat (IMO) but they would be in the "advanced" section.

Overall I really like the outline. :)

Specific notes on content:

I'd like to see some reference to "Campaign" in there somewhere, as maps and tokens are merely parts of a campaign. Perhaps in the "MapTool Windows & Objects" chapter?

Where should saving and loading go? For example, tokens can be saved and reused later. Ditto for maps (imported and exported) and tables. Oh, and there are campaign properties as well: sight, light/aura, health bars, and states. (You already mentioned repositories in your outline.)

I see a section on the drawing tools, but nothing for the GM regarding the fog-of-war? Or do you plan to cover that under "Vision Blocking" and/or "Lights and Sights"? Also, the drawing tools let you draw lines and circles and squares ("Oh my!"), but the template tools are the ones that draw bursts and cones as area of effect images. I'm thinking you might want to separate out the drawing and template tools into a separate chapter or put them in the "advanced" section of the "Maps" chapter -- they're not required to use MapTool for a game.

It may be a pain, but it would be nice to number your top-level entries so that we (forum users) can refer to them easily when thinking aloud about "maybe such-and-such should be in chapter 4"...?

I'm pretty jazzed to see what you come up with! 8)

Gamerdude
Cave Troll
Posts: 89
Joined: Thu Feb 04, 2010 12:17 am

Re: Official(?) MT 1.3 Documentation Project

Post by Gamerdude »

Azhrei - those are all good questions, and I don't have a good answer mainly because I'm still learning MT and have to go by what I am reading on the forums and finding on the wiki and RPTutorial websites. So in part there are plenty of things am not quite familiar with to understand exactly where they would best fit (hence the feedback!)

Thanks
Al B. USAF RET.
*Chief Organizer and Bottle Washer - 'User Creations' Forum*

MT Framework Directory **LISTING** (UPDT 2012-02-10)

User avatar
Raoden
Dragon
Posts: 381
Joined: Fri Dec 18, 2009 2:33 am
Location: San Diego

Re: Official(?) MT 1.3 Documentation Project

Post by Raoden »

Map import and export should have its own (short) section.

"Making a map" should be its own area, too. It should reference a lot of the things Brad talks about in his video tutorials: selecting images that aren't too high-resolution, drawing with textures, copying/pasting, etc.
"Fairy tales do not tell children the dragons exist. Children already know that dragons exist. Fairy tales tell children the dragons can be killed."
- G. K. Chesterton

Wonderful HTML/CSS reference * Color Manager * Token Manager 2.0

User avatar
Azhrei
Site Admin
Posts: 12086
Joined: Mon Jun 12, 2006 1:20 pm
Location: Tampa, FL

Re: Official(?) MT 1.3 Documentation Project

Post by Azhrei »

Raoden wrote:Map import and export should have its own (short) section.

"Making a map" should be its own area, too. It should reference a lot of the things Brad talks about in his video tutorials: selecting images that aren't too high-resolution, drawing with textures, copying/pasting, etc.
I presume the document will take a very basic approach in the beginning, similar to Brad's tutorials. For example, "Here's how you create a map. Notice how you can set the background color and/or texture?" Followed by, "Here's how you can use a tileset to build a map wall-by-wall if you prefer. There are advantages to this technique, as discussed in the advanced section."

Then in the advanced section, cover the nitty-gritty regarding memory and performance differences in tilesets vs. dropping a pre-made map image.

I don't think I'll micro-manage that part of his document until he actually has a first draft to look at. THEN I'll micro-manage the hell out of it!!

(Just kidding. :))

I think there are multiple ways that this could be approached and I'm fine with letting GD decide how he wants to attack it. Since he's learning MT as he goes along, he may choose to simply document his learning process, perhaps going back and changing earlier sections when he slaps his forehead and thinks, "I coulda' had a V-8!"

8)

User avatar
jfrazierjr
Deity
Posts: 5176
Joined: Tue Sep 11, 2007 7:31 pm

Re: Official(?) MT 1.3 Documentation Project

Post by jfrazierjr »

Azhrei wrote: I think there are multiple ways that this could be approached and I'm fine with letting GD decide how he wants to attack it. Since he's learning MT as he goes along, he may choose to simply document his learning process, perhaps going back and changing earlier sections when he slaps his forehead and thinks, "I coulda' had a V-8!"

8)
Azhrei, where does the existing Maptool menu items for the help point to? It would be really nice to be able to point to this document, either on the web or on the local machine, so perhaps a place holder is warranted.
I save all my Campaign Files to DropBox. Not only can I access a campaign file from pretty much any OS that will run Maptool(Win,OSX, linux), but each file is versioned, so if something goes crazy wild, I can always roll back to a previous version of the same file.

Get your Dropbox 2GB via my referral link, and as a bonus, I get an extra 250 MB of space. Even if you don't don't use my link, I still enthusiastically recommend Dropbox..

Gamerdude
Cave Troll
Posts: 89
Joined: Thu Feb 04, 2010 12:17 am

Re: Official(?) MT 1.3 Documentation Project

Post by Gamerdude »

I've gone and numbered the chapters, sections, sub-sections so people can just refer to the numbers. If someone things something is missing, tell us what that is, where you think it should go, and why (remember, MT novice here :shock: ). That also goes for moving anything please.

I am relying on all the experience MT users out there to pick this apart, suggest things, and help shake it out. The better the planned outline the better everything will fall into place and read better. Always going from simple to advanced, known to unknown. Any resource for MT info will be a big help at least for cross referencing info for clarity and accuracy.

MY APPROACH TO THE PROJECT:
I had a professor (later colleague] who had an interesting way to teach programming... you start with a small central idea and slowly spiral your way out through topics getting more and more advanced, and repeatedly touching on the already covered material. This way you built familiarity and retention.

That's hard to do with a written document that won't be covered in a class by a real person, but my outline is actually an attempt at doing just that.

When I teach people RPGs I remind them "don't worry about learning every term and tiny detail right now. I am just giving you a basic overview so later you can at least say 'hey! I heard that term before' and it at least familiar enough you don't feel totally lost".

So for MT it's:
- "ok, an intro, just show you lay of the land, a few key points of interest"
then
- "Ok, now lets look at this again with some more depth, nothing tough but you should be able to find your way around without help"
then
- "Ok, lets start looking at each part and looking under their hoods"
then
- "Now class, time to roll up those sleeves and start pulling out parts, examining them in detail, and begin building things"
and finally, now that they can host a session with some confidence it's
- "Let's look at how to build a all the fancy bells and whistles from the ground up."

What I don't want is how the USAF teaches people to fire an M-16: Four hours of class (dry fire) before you ever put a round INTO the weapon. They follow the same approach as my outline but they take too long to get to the practical part.


Thank you all
Al B./GamerDude
Al B. USAF RET.
*Chief Organizer and Bottle Washer - 'User Creations' Forum*

MT Framework Directory **LISTING** (UPDT 2012-02-10)

Gamerdude
Cave Troll
Posts: 89
Joined: Thu Feb 04, 2010 12:17 am

Re: Official(?) MT 1.3 Documentation Project

Post by Gamerdude »

[quote="jfrazierjrAzhrei, where does the existing Maptool menu items for the help point to? It would be really nice to be able to point to this document, either on the web or on the local machine, so perhaps a place holder is warranted.[/quote]
In the MapTools HELP menu, the option "DOCUMENTATION" takes you to http://www.rptools.net/?page=maptool and "TUTORIALS" takes you to http://www.rptools.net/?page=tutorials

There aren't any help files for the program the way we're use to in a Windows system that I can find.

Al B.
Al B. USAF RET.
*Chief Organizer and Bottle Washer - 'User Creations' Forum*

MT Framework Directory **LISTING** (UPDT 2012-02-10)

User avatar
Azhrei
Site Admin
Posts: 12086
Joined: Mon Jun 12, 2006 1:20 pm
Location: Tampa, FL

Re: Official(?) MT 1.3 Documentation Project

Post by Azhrei »

Here are the three URLs that are currently defined:

net.rptools.maptool.client/configuration.properties:
helpURL=http://www.rptools.net/?page=maptool
tutorialsURL=http://www.rptools.net/?page=tutorials
forumsURL=http://forums.rptools.net/

I would probably link the documentation from the MapTool page on the main site. That way folks browsing the main site or folks who got there via a search engine would be able to find the docs without much trouble.

User avatar
zEal
Dragon
Posts: 944
Joined: Sun Mar 22, 2009 2:25 am

Re: Official(?) MT 1.3 Documentation Project

Post by zEal »

Gamerdude wrote:
CoveredInFish wrote:One question comes to my mind though: what exactly do you call forms? If its really html forms in maptool frames/dialogs then I wonder about their prominent position. It would be more of a subchapter of macro writing.
You are correct on what I say are "forms", and I agree with your thinking to a point but let me explain my thinking.

Macros are used everywhere, not just in forms, and are a huge topic all by themselves. Forms in MapTools are a special container, an interface element that can utilize macros but don't have to. Think of a form as a car, and macros as the engine, electrical system and such. Without them you can design how a car looks, how pieces move around, turn knobs and push buttons. You can make an ugly car nobody will want to get into or a very nice looking car that everyone will want.
Even after your explanation I don't understand why you'd want forms to have their own chapter(?). Sure, there are plenty of macros that don't involve forms, but all forms involve macros. It seems like the best place to write about forms would be in a section/chapter explaining how to get input from a user by using forms or input().

I'm also curious about what Tables have to do with forms; we are talking about html forms in frames/dialogs, right?

Gamerdude
Cave Troll
Posts: 89
Joined: Thu Feb 04, 2010 12:17 am

Re: Official(?) MT 1.3 Documentation Project

Post by Gamerdude »

NOTE: Once posted I realized my reply did not (for me) satisfactorily answer what zEal asked, and thought I had deleted my reply. Upon finishing the re-write I see that I some how screwed up (not good). my apologies for any confusion.
zEal wrote:Even after your explanation I don't understand why you'd want forms to have their own chapter(?).
In going back to the wiki I realized I missed the info on frames and dialogs. If one looks at the wiki topics for Dialogs/Frames and for Forms it is clear that all of these are built with HTML code not the MT macro language. They can just display information OR they can be made dynamic by using macros.

HTML makes the look, the feel, creates the objects that a macro would get information from/put information into IF a macro were to be utilized in the form, dialog, or frame. HTML is 'presentation' while Macro Language is 'function'. A horrible looking form can make even the best macro useless just as a beautifully functional form can be worthless with crappy horrid macro code behind it.

So, Two different languages, two different purposes, and so in my thinking two different (yet related) topics.

zEal wrote:I'm also curious about what Tables have to do with forms; we are talking about html forms in frames/dialogs, right?
I could have sworn when I was going through everything that '.mttables' was on the Wiki page for forms, now I can't find it at all so I am hunting it down to find the proper place for the topic.

Note the changes to the "Forms" chapter.
Last edited by Gamerdude on Thu Jan 20, 2011 6:43 pm, edited 2 times in total.
Al B. USAF RET.
*Chief Organizer and Bottle Washer - 'User Creations' Forum*

MT Framework Directory **LISTING** (UPDT 2012-02-10)

User avatar
CoveredInFish
Demigod
Posts: 3104
Joined: Mon Jun 29, 2009 10:37 am
Location: Germany
Contact:

Re: Official(?) MT 1.3 Documentation Project

Post by CoveredInFish »

I'd probably place the forms chapter behind the macro chapter since its almost impossible to use forms without writing macros.

Plus I think that maptool tables (mttables) has really nothing to do with forms and little with macros and could probably get its own chapter?!

Post Reply

Return to “Documentation Requests/Discussion”