Better setup documentation

[mjvcallibrity]

I am interested in participating in this project, but I am a bit unclear on how to get initially set up and running this project. I would like to have a brief discussion in this issue (or be pointed to a different issue) to help increase understanding around getting a simple example of goby running locally.

After the discussion happens, I would be happy to write up further documentation in the README to enable other interested parties to get up and running with Goby on their own machines. Thanks!

[mjvcallibrity]

Okay. I managed to find main.rb in the res/scaffold/simple/ directory. After gem install goby, I hit a small load error when the program tried to require_relative 'map/farm.rb'. Changing that require to require_relative './farm.rb' fixed the problem and I was able to get the program running successfully.

I'm going to go ahead and make a change to that require_relative call and update the README documentation to include the steps necessary to get the main.rb program up and running.

[nskins]

Hello @mjvcallibrity - I apologize about the lack of setup documentation as I unfortunately became very busy around the time me and the other contributors completed 0.2.0, which is the stable release.

You should not directly run the main.rb you find in res/scaffold/simple. Please see #133 where I explain how to get a simple example running. That res/scaffold directory provides an easy way to start up an example with the goby executable. So please don't make any of those changes you mention in your second comment.

Here's a little direction to get you started. Let me explain the main class types in a Goby project:

• Entity - currently, it's either a Player or a Monster. A Player can walk around on a Map and accepts standard input to all of its actions. The Player can encounter Monsters on the map with which it can battle.

• BattleCommand - a command that either a Player or Monster can execute in battle. For instance, an Attack runs a simple calculation to determine the amount of damage to inflict based on the user's attack and the enemy's defense. An Entity can also try to Escape from battle or Use an item (some BattleCommand examples).

• Item - executes an event when an Entity uses it. For instance, Food can heal a specified amount of HP to the Entity. There are also Items that can be equipped (Equippables) - see Weapon, Helmet, Shield, Torso, and Legs.

• Map - 2D arrangement of Tiles on which the Player can walk. There's a graphical representation that appears to show the Player's current location. You can set a BGM file to play in the background while the Player's on that particular Map.

• Event - Each Map becomes more exciting when you add Events, which can be run by commands from the Player. An Event sits on a Tile and runs some action once it's executed. For instance, there's an NPC that can say something to the Player and a Shop where the Player can buy and sell Items.

Hope that helps. Please feel free to ask any questions you have, whether here on GitHub or via e-mail. And thank you for your interest in contributing!

[mjvezzani]

Thanks for getting back to me so quickly @nskins!

I've recently been looking for an open source project to contribute to, and when I found this one, it snagged my interest immediately. Thanks for explaining the main class types, and also for clarifying how to get up and running with the simple example.

Regarding the original issue I brought up, do you at all feel like there is a need for better README documentation? Or perhaps a documentation directory that explains aspects of the project in more human readable terms? Is that something that you would find brings value to the project? I figure doing so would help me to better understand the inner workings of the project while giving others an approachable documentation to get started with the project.

Just let me know and I'm happy to dig into it. I've probably got around 3-4 hrs/week to put toward this.

[nskins]

I've long wished to have a tutorial that walks through the creation of a simple game. It would hopefully hit on all those points from my previous comment (and probably more). I'm thinking perhaps a tutorial/ directory with part-x-<name>.md files.

I think once users have a clear idea about these concepts it will be more natural to approach the existing Goby docs. As you mentioned, the main problem is the lack of "setup" documentation or even "getting started" documentation. I feel a tutorial would fix that.

As for the README, we might just update the "Getting Started" section to mention the tutorial and link to it.

Does that sound like something you'd like to work on?

[mjvezzani]

That sounds like something I would really enjoy working on. I'm not the very best programmer (I've got a lot to learn about best practices, etc.), but I do enjoy writing documentation.

Initial thoughts on this would be something similar to how many language frameworks structure their tutorial documentation. Usually the first article is a get up and running quickly in which the person creates something that exercises the main concepts of the framework without going into too much detail. Follow up articles then dive deeper into specific sections of the framework. Goby seems like it would lend itself well to this kind of framework tutorial documentation.

Maybe for a first tutorial, walk through creating a simple 4X5 map that has a store from which to purchase things and a monster to fight, allowing a player to buy a sword and kill a monster with it. This should provide a game designer with a quick and dirty introduction to the initial parts of the system they have to interact with.

Thoughts?

[nskins]

Yes that structure sounds like it would work nicely. This is really open-ended so please write whatever feels natural. And let me know if you need more guidance on anything at any time.

…

On Apr 29, 2018 7:29 PM, "Michael Vezzani" ***@***.***> wrote: That sounds like something I would really enjoy working on. I'm not the very best programmer (I've got a lot to learn about best practices, etc.), but I do enjoy writing documentation. Initial thoughts on this would be something similar to how many language frameworks structure their tutorial documentation. Usually the first article is a get up and running quickly in which the person creates something that exercises the main concepts of the framework without going into too much detail. Follow up articles then dive deeper into specific sections of the framework. Goby seems like it would lend itself well to this kind of framework tutorial documentation. Thoughts? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#136 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AHgDjCV636AlWoDla30H1A82nFVzwLUqks5ttkzogaJpZM4TqdBC> .

[mjvezzani]

Cool. I'll go ahead and run with that. For the sake of feedback, does it make sense to continue to ask questions here in this issue so that there is a public record of documentation choices, or would it be easier/quicker to ask questions and get clarification through email?

[nskins]

Either way's fine by me. Neither would be more quick.

[mjvezzani]

Alright, so my first question is about the goby executable. When run, a goby-project directory is created that has a subdirectory of src. Directories within src are battle, entity, event, item, and map, with a main.rb file. All the directories are empty, with the exception of map. Can you explain the purpose of the empty directories? Is that where a user defines new classes that extend the base classes?

I ask the question to understand what someone is supposed to do with those empty directories after they run goby at the command line.

[mjvezzani]

On further inspection, looking that the goby github project (and not the one I created running the goby executable), within each of those directories is a base class file that creates the foundation of other classes within each directory. This is the case for each directory except battle. In the battle directory there is battle.rb and battle_command.rb. battle_command.rb appears to be the base class which the other classes inherit from. It there a pattern to the directory names that I am missing?

[nskins]

There isn't really a pattern to the directories, but the framework just suggests that you place anything related to the idea of "battles" in battle/, "maps" in map/, etc as a good organizational foundation. It's not actually required.

I ask the question to understand what someone is supposed to do with those empty directories after they run goby at the command line.

I usually start by fleshing out what the Map looks like in terms of dimensions and Tile graphics (no content like Events, Monsters, etc. yet). To do this, you could show that subclasses of Tile can be passable (e.g. grass) or impassable (e.g. wall), and that each can have a custom Unicode character appear as a graphic on the Map. From this, you can define exactly how the Map appears graphically to the Player.

You could also briefly mention the other member variables of Tile (and what they do) but then come back to those in later parts of the tutorial.

[mjvcallibrity]

Sorry for falling off the map for a week. I'm interviewing with a few new companies and had an extended technical interview assignment I was working on.

Thanks for the previous comment. I think this will help point me in the right direction in terms of getting started!

[nskins]

No worries. Thanks for the update.

[mjvcallibrity]

So I've managed to work through documenting the Tile class in an approachable way, and I'm now starting with the Map class. In the map class is a function ==(rhs). This is something that I'm not familiar with. Would you be able to point me to some documentation somewhere that explains this, or would you mind explaining it so I can better understand what its responsibility is? I mean, I see that the return of that function is the name of the Map on the right, but I'm still a bit confused by the syntax of that method definition. Specifically the == part before the parameters.

[nskins]

The function ==(rhs) is a member function of Map that overrides the default equality (==) operator. Basically, it says two Maps are considered equal if they both have the same name. It actually returns true or false. We use this to ensure that each Map in the entire game has a unique name; the programmer can then move the Player by specifying the Map name (and a pair of coordinates).

Mathematically speaking, for all Maps m1, m2: m1 "equals" m2 if and only if m1.name "equals" m2.name.

It's an implementation detail - you don't need to touch on it for the tutorial.