Tutorial code needs to be updated
nav9 opened this issue · 28 comments
This is for:
Product Version: jMonkeyEngine SDK v3.2.2-stable-sdk1
Java: 1.8.0_192; Java HotSpot(TM) 64-Bit Server VM 25.192-b12
System: Linux version 4.4.0-150-generic running on amd64; UTF-8; en_IN (jmonkeyplatform)
How to reproduce the issue:
Start the SDK, press F1 to view the tutorials and started trying the beginner tutorial programs.
The issues:
Issue 1:
At least until the first 4 tutorials (HelloSimpleApplication, HelloNode, HelloAssets, HelloEventLoop and possibly more of them), there are tiny issues like the code being:
Box(1, 1, 1);
player = new Geometry("Player", b);
When it should be:
Box b = new Box(1, 1, 1);
player = new Geometry("Player", b);
Also, for example, in the tutorial "HelloInputSystem", there are plenty of errors that show up. One being for this line: inputManager.addListener(actionListener,"Pause");, where the error message says "actionListener has private access in SimpleApplication", or the line inputManager.addListener(analogListener,"Left", "Right", "Rotate"); where the error message is "cannot find symbol variable analogListener".
Issue 2:
When copying code from the tutorial and pasting it into the IDE, at multiple places, an annoying character is present which causes the IDE to show an error saying "illegal character: '\u00a0'". It happens in places like the one I've marked below as "Here". I found that it's a non breaking space character, but since it's annoying to have to keep removing it once the code is pasted in the IDE, perhaps y'all could write a script to remove it from the tutorials.
public class Main extends SimpleApplication {
<----- Here
public static void main(String[] args) {
I guess these are just some simple issues caused because of JMonkeyEngine having undergone some updations, but the tutorials need corrections to remain up-to-date.
Thank you for documenting this issue. Over the years, the JME wiki and the tutorial examples in jme3-examples have gotten out of sync.
Instead of copy-pasting from the wiki, a better way might be to create a new "JME3 Tests" project. The JME3 Tests project should include all the tutorial examples (names beginning with "Hello") but also other example code you may find interesting later. File -> New Project -> JME3 -> JME3 Tests
Thank you Stephen. The JME3 Tests were indeed an excellent way to get started. I'm happy y'all have thought of so many ways to make things simple and well documented for beginners.
However, there are few things I'd still like to mention:
1. It'd be nice if users could be pointed to the JME3 Tests from the JMonkey Homepage itself, else people will end up copy pasting the tutorial code like I did.
2. If possible, it'd be nice to show info on the screen about what controls the users could use to manipulate the scene.
3. Even the JME3 Tests do seem to have problems which require some attention and updation. For example, running the TestPostWaterLake program threw this error:
INFO: Audio Renderer Information
* Device: OpenAL Soft
* Vendor: OpenAL Community
* Renderer: OpenAL Soft
* Version: 1.1 ALSOFT 1.15.1
* Supported channels: 64
* ALC extensions: ALC_ENUMERATE_ALL_EXT ALC_ENUMERATION_EXT ALC_EXT_CAPTURE ALC_EXT_DEDICATED ALC_EXT_disconnect ALC_EXT_EFX ALC_EXT_thread_local_context ALC_SOFT_loopback
* AL extensions: AL_EXT_ALAW AL_EXT_DOUBLE AL_EXT_EXPONENT_DISTANCE AL_EXT_FLOAT32 AL_EXT_IMA4 AL_EXT_LINEAR_DISTANCE AL_EXT_MCFORMATS AL_EXT_MULAW AL_EXT_MULAW_MCFORMATS AL_EXT_OFFSET AL_EXT_source_distance_model AL_LOKI_quadriphonic AL_SOFT_buffer_samples AL_SOFT_buffer_sub_data AL_SOFTX_deferred_updates AL_SOFT_direct_channels AL_SOFT_loop_points AL_SOFT_source_latency
Jun 17, 2019 9:49:40 AM com.jme3.audio.openal.ALAudioRenderer initOpenAL
WARNING: Pausing audio device not supported.
Jun 17, 2019 9:49:40 AM com.jme3.audio.openal.ALAudioRenderer initOpenAL
INFO: Audio effect extension version: 1.0
Jun 17, 2019 9:49:40 AM com.jme3.audio.openal.ALAudioRenderer initOpenAL
INFO: Audio max auxiliary sends: 4
Jun 17, 2019 9:49:41 AM com.jme3.asset.plugins.HttpZipLocator setRootPath
WARNING: Failed to set root path http://jmonkeyengine.googlecode.com/files/wildhouse.zip
java.io.IOException: 404 Not Found
at com.jme3.asset.plugins.HttpZipLocator.readData(HttpZipLocator.java:196)
at com.jme3.asset.plugins.HttpZipLocator.readEndHeader(HttpZipLocator.java:295)
at com.jme3.asset.plugins.HttpZipLocator.load(HttpZipLocator.java:322)
at com.jme3.asset.plugins.HttpZipLocator.setRootPath(HttpZipLocator.java:346)
at com.jme3.asset.ImplHandler$ImplThreadLocal.initialValue(ImplHandler.java:120)
at java.lang.ThreadLocal.setInitialValue(ThreadLocal.java:180)
at java.lang.ThreadLocal.get(ThreadLocal.java:170)
at com.jme3.asset.ImplHandler.tryLocate(ImplHandler.java:178)
at com.jme3.asset.DesktopAssetManager.loadAsset(DesktopAssetManager.java:359)
at com.jme3.asset.DesktopAssetManager.loadModel(DesktopAssetManager.java:416)
at com.jme3.asset.DesktopAssetManager.loadModel(DesktopAssetManager.java:420)
at jme3test.water.TestPostWaterLake.simpleInitApp(TestPostWaterLake.java:81)
at com.jme3.app.SimpleApplication.initialize(SimpleApplication.java:220)
at com.jme3.system.lwjgl.LwjglAbstractDisplay.initInThread(LwjglAbstractDisplay.java:130)
at com.jme3.system.lwjgl.LwjglAbstractDisplay.run(LwjglAbstractDisplay.java:211)
at java.lang.Thread.run(Thread.java:748)
Jun 17, 2019 9:49:41 AM com.jme3.app.LegacyApplication handleError
SEVERE: Uncaught exception thrown in Thread[jME3 Main,6,main]
java.lang.NullPointerException
at com.jme3.asset.plugins.HttpZipLocator.locate(HttpZipLocator.java:354)
at com.jme3.asset.ImplHandler.tryLocate(ImplHandler.java:178)
at com.jme3.asset.DesktopAssetManager.loadAsset(DesktopAssetManager.java:359)
at com.jme3.asset.DesktopAssetManager.loadModel(DesktopAssetManager.java:416)
at com.jme3.asset.DesktopAssetManager.loadModel(DesktopAssetManager.java:420)
at jme3test.water.TestPostWaterLake.simpleInitApp(TestPostWaterLake.java:81)
at com.jme3.app.SimpleApplication.initialize(SimpleApplication.java:220)
at com.jme3.system.lwjgl.LwjglAbstractDisplay.initInThread(LwjglAbstractDisplay.java:130)
at com.jme3.system.lwjgl.LwjglAbstractDisplay.run(LwjglAbstractDisplay.java:211)
at java.lang.Thread.run(Thread.java:748)
I agree with you regarding the thing 1 and thing 2 you mentioned.
The 404 Error in "TestPostWaterLake" is issue #994, which is fixed in v3.2.3 of the Engine and should therefore be fixed in some future release of the jMonkeyEngine SDK.
By the way, there are separate issue trackers for the jMonkeyEngine wiki:
https://github.com/jMonkeyEngine/wiki/issues/new
and the jMonkeyEngine SDK:
https://github.com/jMonkeyEngine/sdk/issues/new
I've opened a new issue (#1128) for thing 2.
Regarding thing 1, perhaps you'd like to improve the jMonkeyEngine documentation wiki yourself. Here is a link to get you started:
https://wiki.jmonkeyengine.org/documentation
Gladly. I had created a tutorial when reporting a problem for PGMPy, but am a bit confused about how the Wiki for JMonkey works. Based on your suggestion, I'm currently assuming the homepage is also somehow a part of the Wiki.
For now I'd request one of y'all to do the updation. I'm currently at a stage where I'm evaluating whether I need to use JMonkey or Chrono for my project. If I choose JMonkey, I'll gladly contribute more.
I misunderstood what you were suggesting in thing 1. The actual homepage ( http://jmonkeyengine.org/ ) isn't part of the Wiki. I apologize for misleading you.
The homepage also isn't the right place to point people to the "JME3 Tests" project template. Mentioning "JME3 Tests" only makes sense once one has downloaded and installed the SDK. The instructions for doing so are part of the Wiki, and the tutorial code is part of the Wiki. One of those places, I think, should mention "JME3 Tests".
If now's not a good time for you to contribute, that's fine. Perhaps I'll do it myself.
I went to document the need for mentioning "JME3 Tests" and in the process I found what was needed.
On the following page:
https://wiki.jmonkeyengine.org/jme3.html#tutorials-for-beginners
It says, " All example code is included in the jMonkeyEngine SDK: Simply create a new project from the JmeTests template."
I can't improve on that. You must've skimmed over it. Or did you bypass that page somehow?
Yes, I read that paragraph and I clearly remember taking note of the part that says "Press F1 in the jMonkeyEngine SDK to browse and search a copy of this wiki’s contents while coding". Especially since that's prominently marked with a red icon. That's how I ended up downloading the SDK and pressing F1 to see the tutorial code and trying them out one by one by copy-pasting.
Honestly, as a beginner, if I see that page even now:
- I'd still think that jme3test is just a folder that contains the same code that I'd see if I press F1 in the SDK. One might also assume those are a set of test cases rather than beginner tutorials (although I agree test cases are a great way to understand a library, beginner tutorials of many libraries are usually created with more comments and user-friendliness than the test cases they create, so that could create a bias in the mind of the reader).
- I'd also not know how much more convenient it is to simply open up the jme3test folder and run it, because I don't know that y'all programmed a nice GUI menu from which I can choose programs to run.
So it'd help to prominently mention that the simplest way for newbies to get started is:
-
Download the JavaMonkey Engine SDK.
-
When opening projects, navigate to the folder containing the jme3test folder and open the project.
-
Run the project and they'd be able to choose tutorial programs to run, from the menu as shown in the screenshot below.
Thank you for your explanation. This issue is a tangle, and you've been very helpful in getting it sorted out.
I recently learned that the wiki in the SDK is “broken” because it relies on an xhtml export of an old version of the wiki. But if that's true, then the current Wiki probably shouldn't be advising users to press F1.
So it'd help to prominently mention that the simplest way for newbies to get started is:
The wiki is massive in size so there are usually many topics covered that the new user will never see. Most don't even bother to read the first page to the bottom. The same page that Stephen linked to.
At the very top of the page, under Tutorials for Beginners, there is mention of the tests. At the very bottom of that same page, JmeTests – The “official” sample project JmeTests.
When following that link you get this. https://wiki.jmonkeyengine.org/sdk/sample_code.html. It explains the tests.
If I had my druthers, all old content would be stripped from the wiki. Like on this page there is mention of asset packs, which doesn't exist anymore. So you will find many things confusing like this throughout the wiki.
Anyhow. I made a change to the page so that now there is a link to the Sample Projects topic, where the tests link is, and removed the admonition to using the SDK F1 help since it is no longer accurate.
I think the tests are all updated and working fine in my experience using 3.3. It looked like to me someone went through them and fixed a bunch of things.
Thanks, @mitm001.
It looked like to me someone went through them and fixed a bunch of things.
Who would do such a thing?? ;-)
My respect for you guys has increased, seeing the sincerity with which y'all work and the fact that there is already a page explaining how to run the tests.
However, I'd still insist on modifying the top paragraphs of the Wiki (and hopefully include the screenshot I attached earlier) to prominently guide new users to running the jme3tests.
This is very similar to how UI & UX users on StackExchange discussed how Steve Harvey could've avoided making the wrong Miss Universe announcement even though to the creators of the card, it appeared obvious who the winner was.
Thanks for that input. Since I'm not very familiar with the design of the Wiki, I'll leave it for others to act on or not.
I'd still insist on modifying the top paragraphs of the Wiki
If you mean on the cover page for the wiki where it details installation, not going to happen here.
As I explained, I added it on the table of contents page, where it should be, where you mentioned actually.
https://wiki.jmonkeyengine.org/jme3.html#tutorials-for-beginners
Who would do such a thing?? ;-)
I knew who. heh.
@mitm001: Yes, my request was to modify the "Tutorials for beginners" section. Removing the "Press F1" was an important part of that, and thank you for doing so.
Ideally, the word "tests" in the phrase "setting up the tests" or even "JmeTests" should be avoided, since it can confuse newbies as being code that run test cases, rather than being beginner tutorials (that's the main reason I didn't consider running JmeTests).
I'll leave that decision to you. Thanks to both of you.
I'm closing this issue.
@mitm001 Thanks for your help addressing this issue.
If I had my druthers, all old content would be stripped from the wiki. Like on this page there is mention of asset packs, which doesn't exist anymore. So you will find many things confusing like this throughout the wiki.
I, too, would like to see old content stripped from the wiki. Is something preventing you from do this?
Nehon has abandoned jMonkeyEngine. It's no longer his decision.
Perhaps it's time to revisit this decision at the Forum.
He hasn't shown any intention of returning, as far as I know.
Keeping this stuff well organized is important for pulling in new users (maybe even separating the concept of examples/tutorials from tests more clearly to avoid confusion), seems worth a revisit.
I miss him too. I don't know why he left.
One more point: It can be really annoying for any newbie to be presented with the JMonkey app settings dialog box and having to click the "Ok" button when running every single app in JmeTests. For a beginner, the settings don't matter at first. They'd just like to run multiple programs and see what kind of functionality JMonkey offers. Especially for people like me, who first evaluate many software libraries before choosing one for my project.
It was such a relief when I found out that dialog box could be avoided by using:
Main app = new Main();
app.setShowSettings(false);
AppSettings settings = new AppSettings(true);
settings.put("Width", 1280);
settings.put("Height", 720);
settings.put("Title", "My prog");
settings.put("VSync", true);
//Anti-Aliasing
settings.put("Samples", 4);
app.setSettings(settings);
app.start();
I understand y'all may have allowed the dialog box to pop up because it's hard to predict what kind of system the user would be running the app on. But perhaps another way to do it would be to have a class that automatically detects their system parameters and chooses the right app settings. Only if it can't figure out the right parameters, the user gets prompted.
One counter point is that a lot of times you want to see how an app behaves under different settings (AA, no AA, gamma, no gamma, etc.)... especially for the tests.
I never noticed that checkbox before. Thanks!
So you guys have actually thought of everything. But perhaps it's the wording or the sequence in which it is presented that makes people skip/miss seeing it. Like I said earlier, this is very similar to how the UI & UX users discussed how the info sequence on the card could've helped Steve avoid making the wrong announcement. I liked the idea behind JMonkey's comic-book-style presentation.