Sorry your browser is not supported!

You are using an outdated browser that does not support modern web technologies, in order to use this site please update to a new browser.

Browsers supported include Chrome, FireFox, Safari, Opera, Internet Explorer 10+ or Microsoft Edge.

AppGameKit Classic Chat / Which parts of the HELP need more detail?

Author
Message
RickV
TGC Development Director
24
Years of Service
User Offline
Joined: 27th Apr 2000
Location: United Kingdom
Posted: 12th Feb 2013 17:41 Edited at: 12th Feb 2013 17:44
Hi,

We want to hear from you in this thread about the commands you want to see more detail help text for in AGK.

When we know which section or individual commands you want help with we'll set to and update it.

You can read all the current help for V1.07 online here;

AGK V1.07 Online Help

So please, post away.

Rick

Financial Director
TGC Team
Ancient Lady
Valued Member
20
Years of Service
User Offline
Joined: 17th Mar 2004
Location: Anchorage, Alaska, USA
Posted: 12th Feb 2013 17:43
Across the board, many commands really could use simple examples of usage.

Not everyone is going to be in a position to buy either of the books that are out or coming out.

Cheers,
Ancient Lady
AGK Community Tester and AppGameKit Master
RickV
TGC Development Director
24
Years of Service
User Offline
Joined: 27th Apr 2000
Location: United Kingdom
Posted: 12th Feb 2013 17:45
Hi Ancient Lady,

To help Paul know which commands to add more advice to he's asked for more specific details. ie not just "across the board".

You can help us by taking a section and listing any commands you need to know more about.

Rick

Financial Director
TGC Team
Ancient Lady
Valued Member
20
Years of Service
User Offline
Joined: 17th Mar 2004
Location: Anchorage, Alaska, USA
Posted: 12th Feb 2013 18:29
Ok. I'll look and find the ones that might need the most help.

Cheers,
Ancient Lady
AGK Community Tester and AppGameKit Master
AgentSam
12
Years of Service
User Offline
Joined: 14th Mar 2012
Location: Virtual Space
Posted: 12th Feb 2013 19:16
Rick,

Shall we also use this thread to point out those commands whose descriptions are simply incorrect (or completely outdated)?

There are a few of those...

Cheers,
AgentSam
The Zoq2
14
Years of Service
User Offline
Joined: 4th Nov 2009
Location: Linköping, Sweden
Posted: 12th Feb 2013 19:54
Quote: "Shall we also use this thread to point out those commands whose descriptions are simply incorrect (or completely outdated)?"


I have found some of those, but I can't think of any from the top of my head right now.

The Editbox commands could use a bit more documentation in my opinion...
ManOfActionTM
13
Years of Service
User Offline
Joined: 16th May 2011
Location: Sahuarita, Arizona
Posted: 12th Feb 2013 20:35
I agree with Ancient Lady, examples for how you can use many of the commands would be useful. I'll see if I can't generate a list as well...
Markus
Valued Member
20
Years of Service
User Offline
Joined: 10th Apr 2004
Location: Germany
Posted: 12th Feb 2013 22:49
for beginners i think one example with all functions of a group
will be good, with direct access from help.
mybe register agk://in windows for open the ide from a html side.
put a link in the web side.
click the link and then the ide open a example for learning.
MikeMax
AGK Academic Backer
12
Years of Service
User Offline
Joined: 13th Dec 2011
Location: Paris
Posted: 13th Feb 2013 02:52
explanations could be done on SetVSync(0/1) ... and the priority of this command with the SetSyncRate command
Hodgey
14
Years of Service
User Offline
Joined: 10th Oct 2009
Location: Australia
Posted: 13th Feb 2013 08:58
Hi Rick,

This is a big ask but would the TGC team consider allowing paid AppGameKit customers to view the AppGameKit source code? At least for just one platform? At the moment I'm not interested in the OpenGL/DirectX stuff but just how AppGameKit manages sprites, images, sounds etc. I've gone through header files before in search for answers to questions (questions only a handful of people would probably ask) but haven't always found answers. I realise that this would introduce a risk of licence/copyright breaches and so completely understand if you guys decline. I can dream can't I?

In regards to documentation:
- We had a discussion about how to free strings returned by AppGameKit in T2 (use delete[]) but I haven't found it in the official documentation. Is it possible to add it somewhere?
- I've noticed there's a GetSpritePtr() in the documentation (listed in the index) but it's not listed in the 'Sprites' section. Since this is a T2 only command I understand that. In my explorations of the AppGameKit headers, I have found a GetImagePtr() command and haven't found any documentation on this. While it's quite obvious on what the command does, if it's in the documentation more people may become aware of it.

Quote: "Across the board, many commands really could use simple examples of usage."

Might need to call upon the community for that one. TGC would have to approve them all though.

joachim
12
Years of Service
User Offline
Joined: 21st Feb 2012
Location: Vancouver Canada
Posted: 14th Feb 2013 01:18
I'm having trubble with

agk::SetSpriteUV()
and
agk::SetSpriteUVScale()
in relation to different Image sizes.


I have Xcode Version 4.6 and iOS 6.1
and v1088.

Thanks
xCept
21
Years of Service
User Offline
Joined: 15th Dec 2002
Location:
Posted: 14th Feb 2013 06:20 Edited at: 14th Feb 2013 06:24
The SetImageMask command, with parameters, is complex enough that I feel the documentation needs expanding. I think code examples would benefit greatly in this case as well.

The PrintImage command does not make any mention that it saves the photo to the media library on iOS/Android (I also understand this command will be improved in 108 final).

Also, I wish that the 'Back' button at the top would return the user to the category index page, instead of relying on JavaScript to return them to whatever page they were on previously. I often hit F1 over a command while programming in AppGameKit to get to the documentation, and am usually interested in viewing related commands. Currently to do this I must hit the Home button, then Commands link, then the Category I'm after (the back button does nothing as it is a new window). I like how DBP documentation includes a "See Also" section with a link back to the category commands and overall index--this would also be a good section to link to directly related commands.
Alien Menace
AGK Developer
19
Years of Service
User Offline
Joined: 11th Jan 2005
Location: Earth (just visiting)
Posted: 14th Feb 2013 07:17
All the commands should have usage examples.

Apps published: 3
The Zoq2
14
Years of Service
User Offline
Joined: 4th Nov 2009
Location: Linköping, Sweden
Posted: 14th Feb 2013 23:05
This isn't realy an issue with the documentation, but it relates to it. I like to view the documentation on my tablet because it allows me to look at it without swapping windows, but there is one issue that is in the HTML/css code. The bar at the bottom with the copyright information sometimes gets stuck in the middle of the screen. This is pretty anoying when it happens over some text. And when the bar is doing what it should, it still cuts of a bit of screen space which is a bit anoying on a phone. I would suggest either moving the bar to the bottom of the page, not the bottom of the screen or removing it enirely on mobile devices.
SteverEno
18
Years of Service
User Offline
Joined: 3rd Mar 2006
Location:
Posted: 15th Feb 2013 00:39
Do it like the documentation for Processing ( http://www.processing.org/reference/ ). Every command has working example code that is just enough to demonstrate what that command does.
AgentSam
12
Years of Service
User Offline
Joined: 14th Mar 2012
Location: Virtual Space
Posted: 15th Feb 2013 06:07 Edited at: 15th Feb 2013 07:00
@The Zoq2:

The header and footer sections in the AGK Online Documentation page are very easy to "fix" using custom CSS. So, if the browser on your phone supports custom CSS, you can fix it for yourself, by adding the following:



I agree with you completely, that fixed header/footer sections are generally a bad idea, and especially so for mobile devices. Which is ironic, since the main target audience for AppGameKit is mobile devices. (I suppose TGC never thought developers might actually use a mobile device to read the docs too?)

It would of course, be best if TGC corrected this for everyone. Though, perhaps there are some who enjoy the fixed headers?

Cheers,
AgentSam
AgentSam
12
Years of Service
User Offline
Joined: 14th Mar 2012
Location: Virtual Space
Posted: 15th Feb 2013 06:34 Edited at: 15th Feb 2013 07:39
May I take up this space for a short rant, please. This could be just a reflection of me getting up on the wrong foot this morning, but some critique may be in order.

It was four days ago, since the OP was posted. And there has been no follow-up posts of any kind from TGC. The same thing happened to another documentation related topic.

It seems obvious that the poster is someone in a management position at TGC, who likes throwing ideas around and delegating tasks to others, but his own follow-through leaves room for improvement. At least from the community perspective; it is tiresome to continue following TGC threads that start with good intentions, and then receive no further attention from TGC. (I was going to wait a week, before posting this rant, but my feelings got the best of me, and the other thread I mentioned has been in the same state for over a month - so it looks like we're developing a pattern.)

Just calling it as I see it, and I'm ready to apologize if I went overboard. Someone please assure me again, that these messages are being taken to consideration by TGC. Thanks.

Cheers,
AgentSam
baxslash
Valued Member
Bronze Codemaster
17
Years of Service
User Offline
Joined: 26th Dec 2006
Location: Duffield
Posted: 15th Feb 2013 10:42
Morning Sam

Rest assured these posts are monitored and we are using them to try to give people what they want and need.

It's funny how people aren't happy with something, we ask what they would like to see improved and people still complain that we aren't listening.

I love my job and even in my spare time (what little there is) I spend a lot of time on these forums from 7am till 11pm and more sometimes. I do this because I want what I have always wanted for TGC to do well so I have some great toys to play with. The rest of the team feel the same


this.mess = abs(sin(times#))
AgentSam
12
Years of Service
User Offline
Joined: 14th Mar 2012
Location: Virtual Space
Posted: 15th Feb 2013 11:50
Morning Bax

I think I might have been overly grumpy this morning, my apologies. I know the team is really busy.

Cheers,
AgentSam
baxslash
Valued Member
Bronze Codemaster
17
Years of Service
User Offline
Joined: 26th Dec 2006
Location: Duffield
Posted: 15th Feb 2013 11:55
No worries, we all have grumpy days... some more than others

Things are really coming together and the hard part of getting this new language going is done. It may not be perfect but it is getting better daily. Despite what information is made available AppGameKit is constantly being improved!


this.mess = abs(sin(times#))
BatVink
Moderator
21
Years of Service
User Offline
Joined: 4th Apr 2003
Location: Gods own County, UK
Posted: 15th Feb 2013 13:02
There is something missing, that will make a huge improvement without adding to the content.

A link back to the command group on each page. For example, all text commands should link back to the text commands page. Then, it is simple to see the related tasks required to make your specific command work.

When I create a text object, I often look at the command set to see what else I may have missed to finetune it. This currently involves Pressing F1, going Home, then drilling back down through the help options. It could be possible in two clicks.

baxslash
Valued Member
Bronze Codemaster
17
Years of Service
User Offline
Joined: 26th Dec 2006
Location: Duffield
Posted: 15th Feb 2013 13:03
Damn straight BatVink, +1 on that one!


this.mess = abs(sin(times#))
The Zoq2
14
Years of Service
User Offline
Joined: 4th Nov 2009
Location: Linköping, Sweden
Posted: 15th Feb 2013 19:34
I found a problem with the SetNetworkClientUserData and GetNetworkClientUserData in the documentation.
http://www.appgamekit.com/documentation/Reference/Multiplayer/SetNetworkClientUserData.htm

The description of the index variable looks like this

Impetus73
12
Years of Service
User Offline
Joined: 28th Aug 2011
Location: Volda, Norway
Posted: 15th Feb 2013 20:40
My problem with the documentation, is that I have a hard time finding commands I need in relations to the command I'm reading about. Maybe make it a bit more hyperlink'y and add a small list of commands you should check out in relations to this one.

I also have the annoying "bar hides the text" problem that T Zoq2 mentioned.

I just received a pre-release copy of the 3D addendum for the AppGameKit book Allistair wrote, and it's looking good.

I still consider his books THE documentation.

----------------
AGK programmer
Did Amiga / AMOS programming in the 90's.
Alien Menace
AGK Developer
19
Years of Service
User Offline
Joined: 11th Jan 2005
Location: Earth (just visiting)
Posted: 16th Feb 2013 09:32
I'd like to see a helpful feature added... when you type a command, I'd like the parameters to appear at the bottom of the IDE so I don't have to look it up...

For example...

I type

SetSpritePosition

and it shows...

SetSpritePosition(SpriteIndex,X,Y)

automagically.

Apps published: 3
DVader
20
Years of Service
User Offline
Joined: 28th Jan 2004
Location:
Posted: 16th Feb 2013 16:25
Okay, off the top of my head, I know a few commands are entirely missing from the help files, include being one of them. I can't remember others at the minute, but am fairly certain there are more. Although most people will know about the include command, many more will not. It is also has a # tag in front of it and no brackets after it, unlike virtually any other commands, but still highlights fine without it, making it most unhelpful to a beginner.
The HTML commands, could definitely use some work, as they are not easy to suss out from the documentation alone.
Also in general, say you press F1 to get info on a command, and you want to find another command of similar type, once you click say setspriteposition, you will get that command come up in your browser, however there is no option to look at other related commands. You have to click home and then search about for it. This I am sure could be fixed so as to make searching the help less annoying.

erebusman
12
Years of Service
User Offline
Joined: 23rd Jul 2011
Location: Sacramento, CA
Posted: 16th Feb 2013 23:32
- in all of the Box2D physics documentation we could use screenshots that demonstrate what the stuff means (written examples are nice but pictures do a million percent more for me). I had to go google box 2d documentation elsewhere to try to understand most of these

- in physics commands you always say

"colConnected - Set whether the two sprites connected by the joint can collide with one another."

.. okay good to know but what are the acceptable values? I still dont know right now what I should be putting here and what the value will mean?

- a pratical tier1 & tier 2 code example would be nice for every command. The tier2 examples took me a long time to understand and I still often find myself saying "what the hell does that even mean" .. a relevant on-page code example would mean a lot to me.

Thats my ideas for the moment. Thanks

Hodgey
14
Years of Service
User Offline
Joined: 10th Oct 2009
Location: Australia
Posted: 17th Feb 2013 01:25
Quote: "I know a few commands are entirely missing from the help files, include being one of them. "

DVader - include. From what I know, the #include keyword is a preprocessor directive meaning its function is carried out before compile time. Same thing with the #constant. But both are there in the documentation.

But I do think there are some commands missing. I can't remember which ones either but I think it revolved around date/time.

DVader
20
Years of Service
User Offline
Joined: 28th Jan 2004
Location:
Posted: 17th Feb 2013 14:51
Ah constant, lol, that's the one, never much use them. If you test either of these commands in 1076 using F1, they do not bring up documentation. If they are listed then they are not easily found, and certainly do not load up any help at all when pressing the F1 key. At least they never have for me since launch. Perhaps it has been fixed in the beta?

TheTeenDevs
11
Years of Service
User Offline
Joined: 19th Aug 2012
Location:
Posted: 17th Feb 2013 18:13
I think that Android tier 2 compiling information needs to be less confusing and have troubleshooting. I found it very difficult to get it working.
Ched80
13
Years of Service
User Offline
Joined: 18th Sep 2010
Location: Peterborough, UK
Posted: 17th Feb 2013 20:43
Couldn't find any example for using "select", etc. I know it's a core function, but I could only figure it out by looking at one of the compiled games.

An example for SetSpriteShapePolygon would be could, as I'm still now sure how you define your own polygon points.

Hodgey
14
Years of Service
User Offline
Joined: 10th Oct 2009
Location: Australia
Posted: 17th Feb 2013 23:30
Quote: "If you test either of these commands in 1076 using F1, they do not bring up documentation. "

I didn't know that but it's probably because they aren't commands/functions, they're keywords...there's a difference.

Quote: "Couldn't find any example for using "select", etc."

Select.

The apparent pattern here is that since the keywords are in a separate group - language it's often overlooked by most users. I personally agree with the setup but a simple solution could be to add a "BASIC Language" link on the Command's contents page.

Talairina
18
Years of Service
User Offline
Joined: 9th Jan 2006
Location: United Kingdom
Posted: 18th Feb 2013 19:35 Edited at: 18th Feb 2013 19:36
GetManagedSpriteDrawCalls() could use more information. Currently it has;



It would be good to know what it mean's by OpenGL call's. For example does it mean how many time's a sync() is done, setspriteposition is done and so on. It's quite vague to me.

It would be very handy to find out as currently in my App for every move the player take's (Turn based game) the integer returned by GetManagedSpriteDrawCalls() jump's 2-3 at a time which is followed by a steady decrease in fps until the game drags at 2-3fps. (This is only noticeable on Android as my Ultrabook show's no sign's of slowing).
Ched80
13
Years of Service
User Offline
Joined: 18th Sep 2010
Location: Peterborough, UK
Posted: 18th Feb 2013 19:38
@hodgey, i stand corrected, although it doesn't state that you can have more than one case on the same line, although this is actually possible:

Quote: "case 1,2,5,7:
print("GOOD"
endcase"


xCept
21
Years of Service
User Offline
Joined: 15th Dec 2002
Location:
Posted: 18th Feb 2013 20:55
None of the 'Language' commands allow the user to hit F1 to view its description in the help--which is why many assume they are not documented as it's hard to find them (separate from the rest of the commands).
Hodgey
14
Years of Service
User Offline
Joined: 10th Oct 2009
Location: Australia
Posted: 18th Feb 2013 21:27
@Ched80: I didn't know about the multiple cases on one line trick. Could be quite handy!

Quote: "None of the 'Language' commands allow the user to hit F1 to view its description in the help--which is why many assume they are not documented as it's hard to find them (separate from the rest of the commands)."

Something for TGC to consider when updating the IDE.

baxslash
Valued Member
Bronze Codemaster
17
Years of Service
User Offline
Joined: 26th Dec 2006
Location: Duffield
Posted: 18th Feb 2013 23:20
I love these forums, I learn something new every day (about the language I use every day). I really should spend more time looking at the help files for all of the commands, not just the ones for tricky to remember commands...


this.mess = abs(sin(times#))
BatVink
Moderator
21
Years of Service
User Offline
Joined: 4th Apr 2003
Location: Gods own County, UK
Posted: 19th Feb 2013 16:50
The CASE find is brilliant, thank you!

It looks like most people would like more streamlined navigation between related commands.

How about links to the supplied examples too, to dive straight into coded examples? That would save adding more example code to the help files.

Markus
Valued Member
20
Years of Service
User Offline
Joined: 10th Apr 2004
Location: Germany
Posted: 19th Feb 2013 18:01

today i had the idea that a simple graphic can often
explain more simply what the command do.
you look at the graphic and say ahhh this is what i need

image filename for help = SetParticlesAngle.png
Ched80
13
Years of Service
User Offline
Joined: 18th Sep 2010
Location: Peterborough, UK
Posted: 19th Feb 2013 20:23
@BatVink, yeah I genuinely think the documentation is good, but more links to the examples and guides would be great.

Ched80
13
Years of Service
User Offline
Joined: 18th Sep 2010
Location: Peterborough, UK
Posted: 25th Feb 2013 08:06
Something else that would help is linking the scan codes to the commands they are used in and vice versa.

xCept
21
Years of Service
User Offline
Joined: 15th Dec 2002
Location:
Posted: 25th Feb 2013 17:58
LoadSubImage - There should be more explanation about the "subimages" text file and some of the terminology is confusing (e.g., "sImageFilename" makes it sound like you need to specify an actual image file but in reality you just need to match the identifier from the subimages file, which must be named "image subimages.txt")

SetSpriteSize - The parameters section is incomplete ("width - the width to use for the sprite, use ")

DrawSprite - Needs a lot more detail to understand the draw order and how it relates to what is displayed on the screen. The various update commands (Sync, Render etc) could definitely use more explanation and examples as well.

I agree with others that small self-contained examples for every command is essential to good documentation. Illustrations or screenshots showing the command's effect would not hurt either. Someone else shared the Processing documentation, which I feel is using some of the best practices out there and really helps you learn the language quick.
Markus
Valued Member
20
Years of Service
User Offline
Joined: 10th Apr 2004
Location: Germany
Posted: 25th Feb 2013 19:12
what about a voting system (mysql db & php) for online help with
a thumb up / down are valid until the help are revised.
lilpissywilly
AGK Developer
13
Years of Service
User Offline
Joined: 10th Sep 2010
Location: Office Chair
Posted: 17th Mar 2013 15:21
SetLightDirectionalDirection under 3D in 1.088

Contains both

SetLightDirectionalColor( lightID, red, green, blue )

and as you'd expect

SetLightDirectionalDirection( lightID, vx, vy, vz )

So I guess set color has been clumped in with set direction. Is all

My hovercraft is full of eels
xGEKKOx
AGK Master
15
Years of Service
User Offline
Joined: 7th Dec 2008
Location: Italy
Posted: 19th Apr 2013 19:16
For iOS all the extra command are ambiguos.
We need to try them much time to understand how they work (if they work).
In fact i'm using obj c to do the same things.

Long life to Steve!
Ancient Lady
Valued Member
20
Years of Service
User Offline
Joined: 17th Mar 2004
Location: Anchorage, Alaska, USA
Posted: 19th Apr 2013 20:40
FacebookInviteFriend - the Definition shows 'szID' and the Parameters shows 'ID' without any description. So, is it a string or an integer and what is it supposed to be?

FacebookPostOnFriendsWall and FacebookPostOnMyWall both need information about all of the parameters (the only one with anything is 'description' and it doesn't explain anything about what it is for). And FacebookPostOnFriendsWall has the same 'szID' and 'ID' issue.

FacebookSetup has the same 'szID' and 'ID' issue, but at least it says what it is for. But it still isn't clear if it is a string or integer.

GetNotificationType should really explain the types of notifications that the integer return represents.

NotificationCreate needs the 'data' field defined and some sort of help about how to use it.

The curious thing is that all of the Notification commands say they work only in iOS but the help page about the server side of Push Notifications is for Android. So 'Notifications' are not 'Push Notifications'?

Basically, there should also be good examples of how all of these things are used.

That's just some of the extras I looked at today.

Cheers,
Ancient Lady
AGK Community Tester and AppGameKit Master
wargasmic
17
Years of Service
User Offline
Joined: 15th Oct 2006
Location: UK
Posted: 20th Apr 2013 04:23 Edited at: 20th Apr 2013 04:39
Just turn the help section into a wiki/user documents section, exactly as it is now but allow users to post their own tips and usages.

If some functions still aren't understood properly, users can post comments asking how it works (help requests?), then TGC can answer/write a short help document or example for that particular function, instead of going all in and trying to write a fully fledged manual all at once.

In shorter terms, an open source collection of help files with official TGC support.

Would save TGC some time(to add my belnd modes), and would probably end up with a load more helpful content.
Impetus73
12
Years of Service
User Offline
Joined: 28th Aug 2011
Location: Volda, Norway
Posted: 21st Apr 2013 20:31
Make a Help forum, and start 1 thread for each command, then people can discuss and explain them to pieces

----------------
AGK programmer
Did Amiga / AMOS programming in the 90's.
Phaelax
DBPro Master
21
Years of Service
User Offline
Joined: 16th Apr 2003
Location: Metropia
Posted: 21st Apr 2013 22:01
How about write something useful for the loadsubimage command. A better explanation of how it works and actually specify somewhere in the help how exactly subimages.txt is suppose to look. I shouldn't have to search the forum to figure that out.

"You're all wrong. You're all idiots." ~Fluffy Rabbit
Caps On!
13
Years of Service
User Offline
Joined: 3rd May 2011
Location:
Posted: 21st Apr 2013 22:41
I like the idea Wargasmic has, have a place on the wiki that allows users to post their own examples or tips on how to use each command.

Truth, Justice, and the Programmer's Way!

Login to post a reply

Server time is: 2024-05-18 08:29:07
Your offset time is: 2024-05-18 08:29:07