Greetings Humans and Forum-Wanderers.
Do we have some kind of fear of the documentation?
Sometimes, when I help people with a simple problem, it seems as if there is nobody on earth that has actually read the documentation. This goes for quest and squiffy.
The docs aren't like the One Ring (I decided to leave a few readers on the curb with that reference, I hope everyone has read The Lord of The Rings) that must not be used at all cost.
Please, can anybody figure this out? It would certainly help us Forum-Wanderers a lot.
Thanks
A lot of people find it hard to navigate docs, for various reasons. That's one of the reasons why teaching requires patience. If you know where to find stuff, give links in response to questions. It requires less effort, and helps a lot. But you'll find that even when the answer is in the manual, it may not be so easy to figure out, for lack of context, examples and so on. That's one of the reasons why teaching requires teachers. Rest assured that people are usually grateful for the help, when you can help them. They know it's work.
A lot of people find it hard to navigate docs, for various reasons.
I suspect this is the big one. Quest allows authors to do a huge range of things, which means there are a lot of docs, which makes it intimidating to new users (especially as it is appealing to less technically-savvy users). If they are trying to do something slightly different, they may not connect the title with what they are trying to do. I have re-organised, which I think makes it easier to find stuff, but I recognise it is not perfect (and if you have suggestions..?)..
The search facility being right at the bottom may not be easy to find, and the top search results are adverts, making it appear it is searching the whole internet and not relevant (the search system is outside my control; cannot help there).
Okay, thanks
That makes a lot of sense
I often find that google Custom Search brings up irrelevant results
I'll keep the discussion going in case anyone has any other ideas
here's some very useful links (quest/coding basics/fundamentals):
https://docs.textadventures.co.uk/quest/ (main page of the doc, you can scroll down to see various topics/guides/help)
https://docs.textadventures.co.uk/quest/tutorial/index.html (Tutorial index)
https://docs.textadventures.co.uk/quest/elements/ (Elements: Objects, Verbs, Commands, Functions, Turnscripts, Timers, Delegates, Etc: these are the main things in quest that you can use)
https://docs.textadventures.co.uk/quest/types/ (Data/VARIABLE/Variable/Attribute/Value Types: Strings, Booleans, Integers: ints, Doubles: floats / floating points / decimals / fractions, Object reference pointers, Scripts, Lists, Dictionaries, etc)
https://docs.textadventures.co.uk/quest/null.html (about / more about: 'null')
https://docs.textadventures.co.uk/quest/scripts/ (most of the built-in Scripts)
https://docs.textadventures.co.uk/quest/functions/ (Functions: categorical order)
https://docs.textadventures.co.uk/quest/functions/index_allfunctions.html (Functions: alphabetical order)
https://docs.textadventures.co.uk/quest/elements/game.html (the required and special 'game' Object: various game-wide/global settings, the special 'pov' feature/functionality, the special 'start' Script, and Publishing Info stuff: author, version/patch history number, year first published, category, description, difficulty, cruelty, sub-title, etc etc etc)
https://docs.textadventures.co.uk/quest/elements/object.html (the built-in Attributes of Objects, including container and other various Object Types / Types: user-level groups/classes, at the very bottom section of it)
I actually do use the Documentiation (admittably, i also read EULAs), but i'd say there's also the issue of some of the Documentation just being so [IMPRECATION AMENDED] sparse with any really helpfull details. (I'll only talk about Quest here, too.)
Just take this as an example: https://docs.textadventures.co.uk/quest/scripts/finish.html . Literally no information given on what exactly this does, and how it affects scripts still running, etc. You're better of learning through trial and error on this one.
There are countless other examples. (Some things were simply left out it seems, like SetLinkForegroundColour which simply is mentioned nowhere to exist. (If i'm wrong about this, feel free to correct me. Doesn't appear under https://docs.textadventures.co.uk/quest/functions/ though.)
I can totally see why the Documentation is such a hurdle for many people. Quest promises you an easy introduction into coding, but when you want to look something up, you pretty much need to know what you exactly don't know to find it. (Imagine it as a foreign dictionary.) It is a tedious paper chase. And if you find it, you get a technically correct, but very short mathematician's answer.
Boo, so much nitpicking here. Of course, i have a suggestion: Can't the Documentation be structured more like a wiki? Currently, if i search for a tutorial about functions, i must look under the headline "More things to do with objects".
PS: https://docs.textadventures.co.uk/quest/guides/using_lists.html is not available, it seems? It's linked from https://docs.textadventures.co.uk/quest/types/objectlist.html .
Maybe I should revise and republish my tutorial game? Might be more useful than I thought?
Just take this as an example: https://docs.textadventures.co.uk/quest/scripts/finish.html . Literally no information given on what exactly this does, and how it affects scripts still running, etc. You're better of learning through trial and error on this one.
That is pretty sparse... I update some of them as-and-when I learn about them myself, so some are better. finish is one I have ever looked at, possibly because I so rarely finish a game (and my last game, Deeper, did not even use it!), so is not done.
If you have anything to add, PM me and I will update it. You may now be the expert on finish, so tell us about it!
Some things were simply left out it seems, like
SetLinkForegroundColourwhich simply is mentioned nowhere to exist.
When I took over, OutputText and its three siblings were missing, and there was no mention of the maths functions either, so it is getting better. I suspect SetLinkForegroundColour is missing because it was designed to be used during the internal initialisation. Do you really want to change the link colours during the middle of a game?
Can't the Documentation be structured more like a wiki?
The answer is probably no; I can change the documents, but not its infrastructure. But what would make in more Wiki-like?
There is a page about functions linked under the "How to" section of the home page. If you failed to find that, then there is an issue there, but it does exist.
I have now corrected the link, thank for pointing that out.
Can't the Documentation be structured more like a wiki?
The answer is probably no; I can change the documents, but not its infrastructure. But what would make in more Wiki-like?
Presumably more cross-links between the various documents, and the ability for any member of the community to contribute. Who can modify the infrastructure anyway? Because sooner or later changes will be necessary. And if it's too hard to change which services are hosted on textadventure.co.uk, the only solution will be to start setting up stuff elsewhere, at the risk of splintering the community. There's already so much discontent with the forum. And non-Quest games can, frankly, be hosted anywhere.
Presumably more cross-links between the various documents,
The current system can do that, it just needs the links added, which, again, is slowly happening.
and the ability for any member of the community to contribute.
It was like that originally. I am not sure why it changed. Currently you need to get permission to modify the files on Github, and I do not know who can give those permissions; possibly only Alex.
Who can modify the infrastructure anyway?
I guess Manowar.
Because sooner or later changes will be necessary. And if it's too hard to change which services are hosted on textadventure.co.uk, the only solution will be to start setting up stuff elsewhere, at the risk of splintering the community. There's already so much discontent with the forum. And non-Quest games can, frankly, be hosted anywhere.
I think this is a real risk to Quest. I think its success compared to other casual systems (i.e., not Inform or TADS) is the web site; people find it first, and can try the web version, and so get drawn in. The recent issues with the servers very much detract from that.
If you have anything to add, PM me and I will update it. You may now be the expert on
finish, so tell us about it!
I figured out finish is not really what i want for my game, and rather settled for an "Endcard" similar to that of the Choice Of Games. (You know, where you can restart, etc.). However, now i'm intrigued, and may start messing around with finish for the joy of it.
Do you really want to change the link colours during the middle of a game?
Infact, yes. I used it in my game for a rudimentary night mode (effectively inverting all colours). But there are other ways this could be usefull (like changing the whole palette when switchign PoV). Nonetheless, it is an existing function, and when there are even the Core Functions (which you shouldn't fiddle) documented, same should go for this one too.
There is a page about functions linked under the "How to" section of the home page. If you failed to find that, then there is an issue there, but it does exist.
Alright on this one, i guess my complain was more about the structuring of the tutorial then, and not the whole documentation.
Presumably more cross-links between the various documents, and the ability for any member of the community to contribute.
Indeed. Many open Source projects (and Quest is Open Source, afterall) use such a style. In the (fairly utopic, i know) imagination of mine, there would be no more need for the "Libraries and Code Samples", since they are includes/referenced directly in the documentation.
Currently you need to get permission to modify the files on Github, and I do not know who can give those permissions; possibly only Alex.
Wait. So the documentation is hosted on GitHub? Or just the Quest code?
There is a Wiki feature built in to GitHub, which will be why it is so popular. Quest has only been on GitHub a few years, which may be why it does not use it.
If you look at the Quest code on GotHub, there is a "doc" folder. That is the live data, the website takes those files are serves them as web pages. I can change files in that folder (and you could do a pull request on your own changes). But I cannot do anything with the pipeline.
I'm sorry for pulling pretty much a necro on this thread, but i just found another prime exampel of flaws in the documentation: https://docs.textadventures.co.uk/quest/using_doubles.html
Read the page carefully. Notice anything? Yes... the page titles Using "doubles" is not telling you how to use doubles. And since Quest's scripting isn't using a declaration of variable type, it's somewhat counter-intuitive and obscure what you have to do. (Using a decimal point, in case anyone's been wondering.)
Doubles are an alternative number system to integers; what is the difference?
Integers are whole numbers (1, 2, 3, etc.), and in maths they can go from minus infinity, through zero, all the way up to plus infinity. Computers have limited space, and in Quest, an integer can go from -2147483647 to 2147483647 - plenty big enough for most purposes.
In mathematics, numbers that are expressed as a fraction or decimal are called "rational" numbers (or "real" number; rational numbers are in fact a subset of real numbers). In computing, these are called floating point number because they have a decimal point that can be anywhere in the number. While rational (and real) numbers can range from minus infinity to plus infinity, floating point numbers are limited because of the space in a computer. They are also limited in terms of their accuracy (how many digits you can store).
More modern computers (like since the eighties or something) therefore offer a second option, a floating point number that uses double the space in the computer, and so can be considerably more accurate.
This, then, is what is known as a "double".
The problem with doubles is that they are approximate. Usually they are good enough, but occasionally you might see something like 6.12303176911189E-17 rather than zero. That is very close, and for calculations good enough, but it does not look right.
Use integers if you possibly can.
You might wonder about how you would handle money, say to represent £2.99, in Quest. Use integers!
Use integers to count the pennies, rather than doubles to count the pounds. You only need to see the pounds value when it is printed, and Quest has the DisplayMoney function to handle that.
For other quantities, you can do similar. If you want to track temperature to the nearest 0.1 of a degree, store the number in tenths of a degree, and output it in degrees (perhaps with the DisplayNumber function).
I have been messing with Quest for over 6 years and besides experimenting for tutorials like this have never had to use anything other than integers. The only time I have seen it come up on the forum was for someone trying to track the progress of a ship across the ocean (or spaceship across space maybe), where the player specifies an angle and distance. For complex trigonmetric calculations, you are into the realm of doubles.
Quest supports all the usual trigonometric functions - and the obscure ones too - and others functions as well.
Note that the trigonometric functions all use radians rather than degrees. If you want to work in degrees, you will need to make your own functions. For example, you could add a function called Sine, returning a double and taking a single parameter, "angle", and have it convert the angle to radians before calling the built-in function.
return (Sin(angle * pi / 180))
The constants e and pi are built-in.
Quest also has these other functions.
If you do a calculation that mixes integers and doubles, Quest will convert the integers to doubles to do the maths, and the result will be a double.
Quest offers four functions that will round your double to an integer. Note, however, that the type will still be double. Rounding a double with the value 4.56 will give a double with the value 4.00.
To display a double to, say, three decimal places, multiple it by 1000, then round it, then divide by 1000.
msg("The objective is " + (Round(distance * 1000)/1000) + " km away.")
To convert to an integer type you will need to use cast (note that there are no quotes around int).
my_int = cast(4.56, int)
This site's link is messed up. I got that from the GitHub page:
https://github.com/textadventures/quest/blob/cb19e55fb28137a2f2bc9806ab58468650239766/docs/using_doubles.md
I'm confused. The link in Zesc's post goes to the page KV posted in full. Was that not the case previously?
Does it?
1 second later . . .
Yep. Sure does.
I didn't even think of checking that . . .
Actually, i am confused now too.
It'd be relatively simple to writte soemthing like "You make a variable a double by storing a number with decimal point in it upon declaration" or something, i think.
I assumed most people would not know what a "double". the word is not exactly intuitive - even floating point and integer may not be familiar terms - so it starts by setting the context, then explaining the word. If you know that stuff, skip ahead,
@Pixie
If I want to find half of some integer variable, the operation I want is x = y / 2.0, while x = y / 2 would do integer division and round it off. I always assumed that's the case in Quest, but never found the need to test it
This is something most programmers will be familiar with, but you can't assume Quest users are all programmers.
If I'm understanding correctly, Zesc is saying that the "using doubles" page should mention this more clearly. Specifically, the page does not appear to mention that you can write 2.0 or similar if you want a literal to be treated as a double. It also spends a whole section on double-to-int conversion; but doesn't mention how to convert an int to a double.
Specifically, the page does not appear to mention that you can write
2.0or similar if you want a literal to be treated as a double.
Yes, this is it. I've had to use doubles for a more accurate percentage counter, and was just trying to find how to make a value a double. Eventually, i found it out, but again, "using doubles" doesn't actually tells you how to use them. All the crazy stunts, but not the basics.
And whilst i agree that most Quest users might not know different sorts of variables, i still come to wonder why "not even floating point" is a term to them. Back when i learned Java, doubles and ints were much more common than wierdo F's.
Coming to think of it... we can't use floating points in Quest, right?
Follow us on Facebook
Follow @TextAdv on Twitter