Update README.

This commit is contained in:
Nolan Darilek 2020-01-15 09:40:45 -06:00
parent 8ffcaf970e
commit ecd3ff6143

View File

@ -4,7 +4,7 @@ _Warning: Still in early development. Only use if you're willing and able to rol
This plugin implements a screen reader for user interfaces created with the [Godot game engine](https://godotengine.org). The goal is to enable the creation of [audio games](https://en.wikipedia.org/wiki/Audio_game) with Godot, as well as to add accessibility functionality to user interfaces and to encourage the creation of accessible games.
For best results, please use [Godot 3.2 Beta 4](https://downloads.tuxfamily.org/godotengine/3.2/beta4/) at minimum. 3.2 has minor accessibility fixes needed to get the most out of this addon.
For best results, please use [Godot 3.2 Beta 6](https://downloads.tuxfamily.org/godotengine/3.2/beta6/) at minimum. 3.2 has minor accessibility fixes needed to get the most out of this addon.
## Why?
@ -12,7 +12,7 @@ As a blind gamer and software developer, I've long had an interest in developing
If so many developers are flocking to engines like Unity, it must be that they derive some advantage from the platform. But because the Unity development environment isn't accessible, I as a blind developer have no way of knowing whether that style of development would work for me. This addon is my way of exploring those possibilities and, with any luck, of making compelling games of my own.
Anecdotally, I've learned that building games with Godot is not only possible, but is becoming very fast as I refine my workflow. My process probably looks nothing like that of most other Godot users. I use the editor to set up scenes, edit properties, etc. Then I drop to a shell prompt, edit the _.tscn_ files by hand, then run the game from the shell. The editor is more of an exploratory interface for the work I mostly do by hand, and has been invaluable at helping me discover property and signal values without pouring through pages of documentation for multiple classes. But even though this approach is a bit more obtuse than just picking a scripting language, what I get from Godot is a set of components that can perform just about any game-related task I need. I also can export games to just about any platform--Windows, Linux, MacOS, Android, iOS, and UWP for the Xbox One.
Anecdotally, I've learned that building games with Godot is not only possible, but is becoming very fast as I refine my workflow. My process probably looks nothing like that of most other Godot users. I use the editor to set up scenes, edit properties, etc. Then I drop to a shell prompt, edit the _.tscn_ files by hand, edit scripts in VSCode, then run the game from the shell. The editor is more of an exploratory interface for the work I mostly do by hand, and has been invaluable at helping me discover property and signal values without pouring through pages of documentation for multiple classes. But even though this approach is a bit more obtuse than just picking a scripting language, what I get from Godot is a set of components that can perform just about any game-related task I need. I also can export games to just about any platform--Windows, Linux, MacOS, Android, HTML 5, iOS, and UWP for the Xbox One.
## Installation
@ -34,7 +34,8 @@ editor_accessibility__enabled = true ; Set to false if you'd like this plugin's
rate = 50 ; range is 0 to 100.
```
This file shouldn't be checked into version control, so add it to your ignore patterns.
5. Launch your project by running `godot -e` in the top-level directory.
5. Optionally, set up Android TTS. After performing [Android export setup](https://docs.godotengine.org/en/3.1/getting_started/workflow/export/exporting_for_android.html) and downloading templates, click _Project -> Install Android Build Template_. Copy, or link, _addons/godot-tts/android_ to _android/godot-tts_.
6. Launch your project in the editor by running `godot -e` in the top-level directory. Or, to launch the game normally, simply run `godot`.
## What is provided?
@ -44,9 +45,11 @@ Add the `ScreenReader` node to any `SceneTree` to make any UI accessible. Many o
`ScreenReader` also customizes keyboard handling to account for the fact that Godot's is somewhat lacking. It attempts to set an initial focus whenever a new scene is initialized so keyboard focus works more often than not.
Further, `ScreenReader` automatically intercepts all touchscreen interactions to emulate basic explore-by-touch and swipe navigation as found on Android and iOS. Currently, left and right swipes emulate _Tab_ and _Shift-tab_. The touchscreen can also be explored, and a double-tap anywhere triggers the last item to gain focus.
### Editor accessibility
Since the Godot editor is itself a Godot UI, the plugin optionally injects a `ScreenReader` node into the editor. The interface isn't accessible enough to create games entirely from within the editor, but games can still be created by using Godot's editor to get an idea for how files should be structured, then editing them by hand in a more accessible IDE.
Since the Godot editor is itself a Godot UI, the plugin optionally injects a `ScreenReader` node into the editor. The interface isn't accessible enough to create games entirely from within the editor, but games can still be created by using Godot's editor to get an idea for how files should be structured, then editing them by hand in a more accessible IDE. In particular, VSCode with its [Godot plugin](https://github.com/godotengine/godot-vscode-plugin/releases) is helpful. Please install a GitHub release, since the version in the marketplace doesn't seem to work with Godot 3.2.
## Gotchas
@ -54,7 +57,7 @@ Here are some issues that I know about now, along with recommended workarounds w
### Tab and Shift-tab stop working.
If focus ever lands outside of a UI widget, Tab and Shift-tab will stop working because there is no focused control for which to find a new focus candidate. I have some defensive code in place to recover from this sometimes, but it still happens on occasion. Save often.
If focus ever lands outside of a UI widget, Tab and Shift-tab will stop working because there is no focused control from which to find a new focus candidate. I have some defensive code in place to recover from this sometimes, but it still happens on occasion. Save often.
This often happens if I run a game from within the editor, then exit the game. Focus seems to land somewhere outside of a control and can't be restored, and my defensive code doesn't kick in.
@ -86,8 +89,9 @@ This is a fun one. First, the controls to do this need to be accessed in a non-s
3. Tab until you reach the tab list.
4. Arrow right to Input Map.
5. Here you can either create a new bindable action by typing a name into the text field, or tab to the tree and select an existing action to bind a new key/controller to.
6. When in the tree, you'll need to access controls for the individual items. Godot is a bit odd in how it associates controls with tree items. Sometimes they're context menus. Others, as here, they're a horizontal row of buttons in one of the tree row cells. To access these, select an action, arrow right twice, and use Home/End to switch between individual buttons on each row.
7. If you select the option to add a key to an action, focus lands in a dialog. You won't get any speech for this. I think you're supposed to do this by pressing the desired key, then clickling a Close button. Naturally, for us this would bind everything to _Space_ or _enter_. Instead, the addon closes the dialog automatically after five seconds, so press your desired key or combination and wait. Pressing a second key or combination clears the first, so if you make a mistake, just press the correct key combination. You won't get speech feedback until the dialog closes.
6. When in the tree, you'll need to access controls for the individual items. Godot is a bit odd in how it associates controls with tree items. Sometimes they're context menus. Others, as here, they're a horizontal row of buttons in one of the tree row cells. To access these, select an action, arrow right twice, and use Home/End to switch between individual buttons on each row. There should be an _Add_ button of some sort. Select it and press _Space_ or _enter_.
7. You then land on a popup menu allowing you to bind a key, joystick button, etc. Arrow to _Key_ and press _Enter_.
8. If you select the option to add a key to an action, focus lands in a dialog. You won't get any speech for this. I think you're supposed to do this by pressing the desired key, then clicking a Close button. Naturally, for us this would bind everything to _Space_ or _enter_. Instead, the addon closes the dialog automatically after five seconds, so press your desired key or combination and wait. Pressing a second key or combination clears the first, so if you make a mistake, just press the correct key combination. You won't get speech feedback until the dialog closes.
A better workflow for this is welcome, but it took so long to figure out how to *reach* this dialog that, when I finally did, I was just damned happy to get *anything* working. :)
@ -97,6 +101,8 @@ Note that _right-arrow_ only navigates between cells in a row for expanded tree
There's no keyboard-equivalent for this, but fortunately the addon has your back. Use the _Application_ key as you normally would. Note that this key performs a right-click. I can't guarantee that will always open a context menu, but it does just that for the scene tree and other nodes with documented context menus.
Note that right-clicks are currently a bit broken. I have to manually position the mouse and inject the correct events, but I seem to be picking the wrong coordinates. Sometimes it works, others it doesn't. Help welcome.
### Some controls don't work.
Working on it. Help welcome, since sometimes I can't figure out how a control is intended to work.
Working on it. Help welcome, since sometimes I can't figure out how a control is intended to work. Sometimes keyboard support isn't implemented at all. Others, I'm not hooking the correct events. This is one huge puzzle.