Documentation - Better controller documentation/tutorials

[Cleptomania]

Currently there is only two examples for using controllers in Arcade. The dual_stock_shooter and sprite_move_controller examples. Outside of these examples we don't really have a section covering using either the controller or joysticks API.

While these systems are basically just aliases of the Pyglet API, it is probably something a lot of newer users would be interested in, and it may be confusing if they need to go to the Pyglet documentation for any information about it. It would be good to have a section in the programming guide, or a more thought-out tutorial covering it.

[JDLiang100]

Hello, my team and I are part of a Code Day project. We are currently working on this ticket, but we would want to clarify the end result of our work. We have looked at the dual_stick_shooter and sprite_move_controller files and noticed that these are python files, however the files in the programing guide only include rst files. We are creating 2 rst files, controller and joystick, that describes their implementation. Could you please confirm if we are in the right track?

[pushfoo]

@JDLiang100
I think there is a misunderstanding. The .rst files are a documentation format and are not executed. You should be creating .py files, though you can create a single one to hold two classes if you'd prefer.

1. Which version of arcade are you using?
2. If you find it more convenient, you can also get real-time help via to get help via the arcade discord server

[pvcraven]

The .rst are 'restructured text' documents and this is what is used to generate the website and its documentation.

The 'include' statement here:
https://github.com/pythonarcade/arcade/blob/development/doc/example_code/how_to_examples/dual_stick_shooter.rst?plain=1#L16

...grabs the source code of the example .py program and includes it in the web page. So examples really needs the following:

• The .py python program
• A .rst file that includes the python and generates a web page people can see
• A .png for a screenshot
• An entry in the index so people can find it.

[Aurelioghs]

Hi, my team has looked at the source code of the arcade game file, and we noticed the Sprite_move_controller.py and Sprite_move_joystick.py already exist. We are still confused about what our task is in this issue. May you please provide further clarification on what our task is?

[pvcraven]

Include an explanation about using joysticks.

• The terminology (game controllers, joysticks, history on why these are confused, buttons, force feedback)
• The fact it sits on top of pyglet
• How to use buttons
• How to use hat
• How to use ranged triggers (like for acceleration)
• Different types of controllers
• How the (-1.0 to 1.0) range works
• Deadzone
• See https://learn.arcade.academy/en/latest/chapters/19_user_control/user_control.html#moving-with-the-game-controller for some ideas

[Cleptomania]

The main goal behind this issue was to create more written documentation covering the controller API and it's usage, as opposed to just straight examples. Right now all we have is the example code but no real docs covering the greater API or anything about it.

[Cleptomania]

#1590 Has been merged in for this. It covers most of the API, however I do think we could still use some better examples at some point, so I'll leave this open if anyone wants to add more tutorial/examples, it is an easy place for new contributors to get started.

A great place for an example would be adding controller support in a chapter of the platformer tutorial.