Skip to main content

On Sale: GamesAssetsToolsTabletopComics
Indie game storeFree gamesFun gamesHorror games
Game developmentAssetsComics
SalesBundles
Jobs
TagsGame Engines

Documentation Sticky Locked

A topic by Adventuron created Jan 24, 2020 Views: 508 Replies: 39
This topic was locked by Adventuron Feb 05, 2020
Viewing posts 1 to 10
Host (2 edits)

What follows is the suggested study path for complete beginners.

1 - Watch The Introduction

Watch this video for at least 10 minutes.


2 - Browse the HTML Documentation

Html documentation is available here (Section 1 to 7 is tutorial how to make a full sample game, section 8 is the reference guide, section 9 is code snippets).  

This documentation contains the full Adventuron Classroom tutorial,  which is quite large. Best to focus on section 10, which is the reference guide.

Submitted (3 edits)

I think it is the theme, where I can ask development questions. To begin:

1. Is changing the TWO theme is permitted or we have to strictly use it as it is?

2. If changing is permitted, what the way to apply each treasure it's own color? Got it

3. What the right way to build conversation with an NPC?

4.  How to implement "Look around" messages?

5. How to change default messages for "Can't take", "Not here" etc.?

I've read the docs, but found nothing for this questions.

Host (2 edits)

1. Yes, the theme is changeable. You need to create a theme in a themes section. You MUST however use the treasure_room = your_treasure_room_id and the redescribe = auto_beta 

Beware, a bug exists that stops control + space working in a theme that uses extends = ????, so if you want to use control + space in a theme, I recommend you comment out extends = two beforehand. This bug is in the editor only, not in the game engine.

start_theme   = my_theme
treasure_room = my_treasure_room
redescribe    = auto_beta
// Game code here ......
themes {
   my_theme : theme {
      extends = two
      // Your specialisation goes here (font changes, message changes, etc) ....
    }
}

2. You can make each treasure its own colour by setting up an explicit colour for the object text per-object

gold_lamp : object "<gold lamp<#rgb>>" at="start_location";

Click this link to see  the different text formatting codes.

3. Conversations with NPCs is pretty tough in general given the constraints of the jam. One approach might be to response to TALK XXXX (where XXXX is an npc name) randomly with "ASK ....." or "TELL .....", then write ASK and TELL handlers for the with the noun representing the topic rather than the NPC name. In this case, you would struggle if the NPCs can move. This is all down to the jam constraints. You might also consider an ask_string attached to TALK XXXX (charactername), and print out TOPIC? before taking the string. That way you can make sure you are never handling more than two words.

You can find a sample use of ask_string here.

4. LOOK AROUND messages? You mean examine objects? Or responding to LOOK AROUND? If it's the latter, then I recommend not responding to that. Adventuron uses standard text adventure convention that LOOK by itself will redescribe the current location. LOOK OBJECTNAME or EXAMINE OBJECTNAME or LOOK AT OBJECTNAME or X OBJECTNAME, will map to the examine message (or handler) for the object. LOOK AROUND shouldn't really trigger anything, as most people wouldn't know to type that so if you depend on that, it might be hard.

5. Changing the system messages is a matter of pressing control + space inside a theme (see the snippet above), and there is a section called system_messages {}. By default the TWO (theme)  system messages are short. You can override the full set, or particular ones as you see fit. If you want to use CONTROL + SPACE in the theme section, make sure you don't extend the TWO theme whilst editing (due to an editor bug) - will try to get this fixed soon.

Submitted

Thank you.

About "look around" - yes, I meant response to this command. I have an idea of mechanics based on “look around”, but if it is so difficult, then maybe I will have to come up with my own expression.

Thank you for the "ask_string" hint, that is exactly what I was looking for.

Submitted

4. Please don't use LOOK AROUND, as this is what the basic room description gives you. The convention for two-word input is VERB NOUN and "AROUND" is not a noun, so no one will think to use it. If you want to provide more details, then use EXAMINE OBJECT or, if you insist, SEARCH OBJECT. Some authors use EXAMINE and SEARCH to mean different things, but SEARCH is usually frowned upon. For example, ignoring the two-word restriction, imagine you're in a barn with a haystack:

>EXAMINE HAYSTACK
That would be a good place to hide things.
>SEARCH HAYSTACK
You find a needle.
>SEARCH HAYSTACK
You don't find anything else.

Don't forget to prevent the second search from finding the needle again!

Host

I personally don't recommend the use of examine and search when applied to the same object in text lite games. It's just two commands you have to try for every noun and it slows down the flow. If there is something to be discovered, then examining something should be enough to reveal it. But this is just a personal opinion.

Submitted (1 edit)

I agree. That's why I used an example without the two-word restriction. You can make SEARCH a synonym for EXAMINE, but a better way is to have a handler for SEARCH that says, "Use EXAMINE.", then there is no doubt that you don't need to use SEARCH.

Submitted

Yes, I've already got it. I came up with another mechanics that fit into the story.

Submitted

Why is Examine and Search not a two word restriction?  Your example only uses two words for each command. I personal have used Examine and Search like this, because I see Examine as purely a visual look at the item, where as Search is a much more detailed hands on examination of an object. I may have to re-think some of my adventure if this isn't allowed. ;)

Host

I do think that using EXAMINE and SEARCH as separate verbs makes gameplay a bit of a chore.

Essentially examine and search play the role of revealing something hidden, and if it is clear that SEARCH needs to be used sometimes, it forces the player into EXAMINE ing and SEARCH ing for every object in the game. I think it's reasonable to examine most objects once, to get a clue, but SEARCH ing is essentially a deeper examine, that may or may not have a custom response. It places a huge burden on the player to do everything twice.

MOVE, PUSH, PULL, TALK, SWIM, THROW, LIGHT, ... all of these are individual actions, but requiring a deep examine isn't really an act of creativity by the player. It just forces the player to type EXAMINE OBJECT then SEARCH OBJECT, and with some players not expecting to search at all.

I'll write something in the rules about this, but if you have a game that absolutely requires search, then it'll be permitted.

Submitted

I see what you mean... what if the first examine command reveals in its description a second potential item to examine.... for instance 
EXAMINE TABLE
THERE LOT'S OF BROKEN POTTERY HERE
EXAMINE POTTERY
YOU FOUND SOME MOLDY CHEESE!
The pottery doesn't become a found object but it is reveal as a secondary item for the player to examine? Would that be ok/better?

Host

Yes, this approach is better. Make sure you create the pottery as a listed object too (scenery). You can also play the : success; command to give an audio clue that the player made some progress.

Submitted

Actually reviewing my game. I've only got two places where the Search command is used without the back up of Examine. So a short rework will fix that, so its not a big deal for me to take Search out of the game. Makes things simpler to be honest. ;)

Host

Separate point, but be sure to select "MENU / SAVE FILE" regularly. Also set up the game_information / game_name field as soon as you can too.

Submitted (2 edits)

And another couple of questions) Sorry for disturbing and for my bad english.

1. About restictions.  The rules say "Locations descriptions [...] should be a maximum of TWO words.".  Does this apply only to the title or also to the on_describe section?

2. Is there a way to automatically display all strings uppercase as recommended in the rules?

Host

1. The title of the room is has a two word limit (no room description permitted, the title is the description). The on_describe section can have one per-room incidental message (as in TWO when you enter the room with the dog and the dog says "WOOF, WOOF". This is an incidental message that could be chained to on_describe {} or on_tick {}, it would be against the spirit of the jam to chain together many messages like this as a way of creating a longer description of a room. The limit for these messages is six words, but as Garry said, you can aim for two words too if you feel like a challenge.

2. If you update the Adventuron application (to beta 19), then the TWO theme will now automatically enforce all-caps. You don't have to use the TWO theme, and you can modify the theme if you wish.

Submitted

1. I interpret the rules as meaning location descriptions are up to two words, but other messages (including on_describe) are up to 6 words. Personally, I'm trying for two words for everything.

2. If you use the two theme or extend the two theme, it does this automatically. If you want to use your own theme, use the following inside your theme:

lister_exits {
   exit_list_capitalization = upper
}
lister_inventory {
   header_capitalization = upper
}

lister_objects {
   header_capitalization = upper
}
theme_settings {
   header_capitalization = upper
}

I might have missed something, but I think that covers most of it.

Submitted

Thanks for the reply. I meant capitalize strings in : print "String" commands. Now I guess that I just have to write them in upper case from the very start.

Submitted

Yes, I believe so.

Host (2 edits)

As of the most recent beta (beta 19), if you use the TWO theme, or a descendent of the two theme, then the entire game will be capitalized whether or not your print messages are capitalized or not. No need to manually capitalize your print messages.

To override this setting (you only need to do this if you DO NOT WANT allcaps:

start_theme = my_theme
// Your game code here
themes {
   my_theme : theme {
      // Inherit all the settings from the TWO theme
      extends = two
      theme_settings {
         capitalization = original | upper | lower | camel
      }
   }
}
Submitted

Amazing! Thanks! That's exactly what I want!

Submitted

This seems to be a bit buggy at the moment. I wanted to use original and nothing changed except for exit list header. Everything else was upper. I had to resort to the old way of doing it, but I had to override the new capitalization setting as well, or everything still reverted to upper.

Host

Please can you provide small sample of this. The capitalization setting is supposed to be an ultimate override of case except if it is set to original. That is, the per category capitalisation still stands if set to original. lower, upper and camel will override all settings. Original won't override the granular settings (such as the Lister capitalization settings). Maybe I'll change the case setting default to "unaltered" instead of original? Or just document it a little bit more?

Submitted

I'll email something tonight.

I was able to successfully change header and text body colors by extending the two theme, but it's unclear to me if there's a way to change the horizontal seperator to a color other than red at this point. Adventuron documentation seems to indicate that it is set to a value of  'adv_line_red' and implementation is subject to change. I'd like to have a way to set it to a color of my choice from the default palette, but I understand if that hasn't been implemented yet. As a follow up question is there a way to replace the values of the default palette with 16 colors of my own choosing?

Host(+1)

Custom palettes are absolutely in the plan, but not implemented yet. You can however use rgb values for most colours, e.g. #000 - #fff.

There are a tiny amount of fixed separators in adventuron and eventually you'll be able to use specific codes to style them to any colour, but there is a more powerful way of providing separators (beta, so may be bugs)....

Step 1 - Create an 8x8 tile in mspaint, paint.net, gimp, or www.pixilart.com  - save the tile as a PNG. Make sure the background colour of the tile is the same as the background colour (paper) colour of your game, or better yet, is transparent.

Step 2 - Select MENU / Import in the Adventuron editor window, to import the PNG as a graphic asset. After importing, note the ID of the imported PNG in the assets{  graphic {} } section,

Step 3 - Create a separators section in the assets{} section and reference the number of horizontal pixels in your tile, and reference the graphic id of your png tile.....

   separators {
      my_sep : separator tile = "your_imported_png_graphic_id_here" horz_pixels = "8" ;
   }


Step 4 - Now reference your separator in the layout section. SB = status bar, O = object list, X = exits, SEP "my_sep" = id of separator. 

   my_theme : theme {
      extends = two
      theme_settings {
         layout = SB O X SEP "my_sep"
      }
   }

To see what this looks like in action (this is using a custom font too)....

Here is an 8x8 tile I just made now (I upscaled this to 768px for posting here, so don't import this one):



Now, following the guide shown above (and also following the guide elsewhere in the forums for setting a new font), the screen might look like this:

themes {
   
   my_theme : theme {
      extends = two
      theme_settings {
         font = userfont_dead_forest
         layout = SB O X SEP "my_sep"
      }
      screen {
         status_bar_padding_bottom  = 2
      }
      colors {
         status_bar_paper            = #55e
         status_bar_pen              = #ee0
      }
   }
}



Submitted

Woohoo! That works.

Very cool, that's way more powerful than I expected. Thank you for the thorough reply!

Submitted

Hello again. I've cant get how to use the "random" function. I've got this code:

integers {
   s_code_1: integer {(random(1))};
   s_code_2: integer {(random(1))};
   s_code_3: integer {(random(1))};
}

And then this:

strings {
   s_code : dynamic_string {(
      s_code_1 + "" + s_code_2 + "" + s_code_3
   )} }

And after printing I get:

-2147483648-2147483648-2147483648

If I don't use "random", everything is ok:

integers {
   s_code_1: integer "1";
   s_code_2: integer "0";
   s_code_3: integer "1";
}

Prints as:

101

WAIDW?

Host (1 edit)

Hi, 

Sorry about this,

Try this:

 integers {
   s_code_1: dynamic_integer {(random(1))}
   s_code_2: dynamic_integer {(random(1))}
   s_code_3: dynamic_integer {(random(1))}
}
Submitted

Yeah, that works, but it changes on every tick what is against the idea that it should be randomized only on game start.

Host

Yes, dynamic integers are reevaluated every time you reference them.

What you want then is something like this:

integers {
   s_code_1;
   s_code_2;
   s_code_3;
} on_startup {
   : set_integer var = "s_code_1" {(random(1))}
   : set_integer var = "s_code_2" {(random(1))}
   : set_integer var = "s_code_3" {(random(1))}
}
Submitted

Oh, so this is what the right solution looks like. Thank you.

Host

Glad I could help :-)

Submitted(+1)

And the last one (I hope :D) question.  Where I can define "end game message(s)"? Is changing the theme is the only way?

Host(+1)

Sorry about your other issue today truly. Going to answer this anyway...

There are two ways. The "win game" message can be defined in the theme

start_theme = my_theme
themes {
   my_theme : theme {
      extends = two
      system_messages {
         all_treasures_found_win_game  = Congratulations, you found all the treasures. You have won!
      }
   }  
}

Way 2

Remove the default win-game logic, by creating a bespoke treasure hunt mode. If you don't choose "bespoke" here, then Adventuron will add code like this automatically to your on_tick {} handler, and reference the system_messages field to obtain the win game text. If you specify bespoke here, it stops Adventuron from administrating the win game logic, and you can do what you like in the win game sequence.

game_settings {
   treasure_hunt_mode   = bespoke
} on_tick {
   : if (treasure_deposited() == treasure_total()) {
      : print "WIN GAME MESSAGE !" ;
      : success ;
      : win_game ;
   }
}
Submitted

Oh, the second way is exactly what I want. Another question referencing to this: is this a way to clear screen to show text only like startup message - without header etc?

Host

There are two ways ....

The first is per-theme config (applies to all clear_screen commands) :

   my_theme : theme {
      extends = two
      theme_settings {
         hide_status_bar_on_clearscreen = true
      }
   }

The second is per clear-screen setting (overrides the theme default):

: clear_screen hide_status_bar = "true" ;

In beta 20, I changed the theme default for the TWO theme to hide the status bar on clear screen by default.

The status bar still returns when the location is re-described, and it seems like this is the most sensible default, hence the change.

Submitted

Amazing, thanks a lot.

Host

--- I'm locking this tread now, as it kind of went off topic --- 

Design questions should go to the DESIGN QUESTIONS thread.

Adventuron questions should go to the ADVENTURON QUESTIONS thread.

----- Locked ----

Host locked this topic