Skip to content

Commit 4cd2a69

Browse files
authored
Merge pull request #225 from endlessm/doc-updates
Doc updates
2 parents d02b932 + 0d51459 commit 4cd2a69

File tree

2 files changed

+168
-8
lines changed

2 files changed

+168
-8
lines changed

addons/block_code/README.md

Lines changed: 20 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -11,14 +11,12 @@ Our aim is to reduce the learning curve faced by learners who are on the early p
1111

1212
With this project, we aim to reduce the height of the mountain that such learners have to climb. Specifically, we aim to eliminate the requirement of learners having to simultaneously learn to code while building their first games. Instead of writing GDScript to implement games, this plugin enables learners use block coding. Tools like [Scratch](https://scratch.mit.edu/), [Blockly](https://developers.google.com/blockly), and [MakeCode](https://www.microsoft.com/en-us/makecode) have demonstrated that block coding can be much more accessible and intuitive to beginners than textual programming—we are bringing those concepts into Godot to help learners become familiar with some aspects of Godot itself while simplifying the creation of their first games.
1313

14-
### Constraints
15-
16-
In order to be learner-friendly, we have to implement blocks at a suitable level of abstraction. For example, in GDScript you would typically move a sprite around the screen by examining input events and adjusting a sprite's movement vector accordingly—but we do not wish to express this level of detail in blocks. Instead, we lean much more towards the kinds of blocks you can find in MakeCode Arcade, such as having a single block for "move mySprite with buttons".
17-
18-
Expressing an appropriate layer of abstraction is perhaps the most challenging aspect of this project, and will likely place limits upon what can be achieved with this tool. We do not aim to express the full power of Godot & GDScript with this block coding plugin, but rather, our objective is to provide a gentler introduction to Godot for learners, such that they can get familiar with other aspects of the Godot Editor and learn programming concepts while creating basic games. We envision that learners would use block coding as a stepping stone and then later progress onto learning GDScript.
14+
In order to be learner-friendly, we implement blocks at a suitable level of abstraction. For example, we have blocks that allow the user to trivially connect keyboard input to the movement of a particular game element, and to make the score show up on-screen. That abstraction does place limits on what can be achieved with this tool, while still allowing us to provide a gentler introduction to Godot for learners, such that they can get familiar with other aspects of the Godot Editor and learn programming concepts while creating basic games. We envision that learners would use block coding as a stepping stone and then later progress onto learning GDScript.
1915

2016
That said, we are in no way opposed to having this project grow to be able to create more complex games, as long as it does not negatively affect the experience for early stage learners.
2117

18+
See our [pedagogy and audience documentation](docs/PEDAGOGY.md) for more info.
19+
2220
## Getting Started
2321

2422
1. Install the plugin through the Godot AssetLib searching for the name
@@ -32,11 +30,11 @@ That said, we are in no way opposed to having this project grow to be able to cr
3230

3331
2. Make sure to enable the plugin in **Project****Project Settings****Plugins**.
3432

35-
3. You're ready to get started! Open a scene, and add a **BlockCode** child node to any node in the scene using the **Add Child Node** menu dialog.
33+
3. You're ready to get started! Open a scene, select a node, and observe that there's a **Block Code** section within the lower central pane of the Godot editor, where you usually find debugging, animation and shader functionality. Click **Block Code** and then use the **Add Block Code** button to create a block canvas.
3634

37-
4. The **Block Code** editor will open in a new tab. Drag blocks from the picker and snap them together to create a script. You can switch to other Block Code scripts by selecting the respective BlockCode node in the scene tree.
35+
4. Drag blocks from the picker and snap them together to create a script. You can switch to other Block Code scripts by selecting the respective node from the scene tree.
3836

39-
5. **Run** the scene to see your Block Code scripts in action. Block Code scripts are attached to the BlockCode node's parent, and are saved to the scene.
37+
5. **Run** the scene to see your Block Code scripts in action. Block Code scripts are saved within the scene.
4038

4139
If you clone the plugin's git repository and open it in Godot, you will be presented with a block-built Pong game as an example.
4240

@@ -50,6 +48,20 @@ We will now seek feedback from learners, educators and game makers, as well as r
5048
- Should this be a plugin or an extension?
5149
- Should blocks generate GDScript or be dynamically executed?
5250

51+
There is no language or data format stability implemented or expected in these early stages. If you upgrade the block coding plugin within an existing project, expect any existing block scripts to stop working and need reimplementing from scratch. For now, you probably want to avoid updating the plugin within your project if it's meeting your needs, or only doing that very sporadically. We will consider offering stability guarantees in future stages of development.
52+
53+
## General user guidance
54+
55+
Block scripts run against the node where you created them. The "Queue Free" block is going to free that node, not any other.
56+
57+
The selection of available blocks varies based on the node type. For example, create a block script on an `Area2D` and you will notice that you have an `On body entered` signal handling block available. Create a node script on an `AnimationPlayer` node and you will observe blocks for starting and stopping animations.
58+
59+
If you wish to switch context to another node, you need to define a function in that other node, and then call it. Once execution jumps into that function, blocks will now act against that other node, and you'll have access to type-specific blocks belonging to that other node. You'll need do this kind of thing if you want to trigger the freeing of another node, or trigger an animation to start playing. This is both strong in conveying the concepts of objects and encapsulation, while also a bit tedious - we may revisit in future!
60+
61+
We have some high level blocks for simplifying common game elements. Add a SimpleCharacter node to get a game element that can be connected to keyboard input with just one type-specific block. Add a SimpleScoring node to display a score on-screen, accompanied by simple blocks for adjusting that score.
62+
63+
Lean into animations! Godot's animations functionality goes beyond just simple animations of graphics. You can do so much by combining block coding with Godot's powerful animations editor.
64+
5365
## Feedback
5466

5567
Please share feedback in the [Godot Forum Block Coding thread](https://forum.godotengine.org/t/block-coding-high-level-block-based-visual-programming/68941).

docs/PEDAGOGY.md

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
# Audience, objectives and pedagogy
2+
3+
This document aims to outline the motivation for the creation of the block
4+
coding plugin, the intended audience, design goals and non-goals.
5+
6+
Note that the design, the pedagogy, and the tool itself are all under
7+
evolution. This document aims to describe the direction we see ourselves
8+
going in; the actual tool itself may be a bit 'behind' in the implementation
9+
of these principles.
10+
11+
## Overall motivation
12+
13+
We want to engage the largest possible audience in game creation, with a
14+
particular focus on young and underserved audiences. We aim to grow the game
15+
creation spark in those that didn't know they had it, and help aspiring
16+
game creators step towards becoming expert users of the Godot engine.
17+
18+
Learners on this journey must face a tremendous learning curve. Godot is
19+
very powerful, and it is also complex. Learners within these groups face
20+
numerous challenges in order to become proficient at Godot, and within those,
21+
the most significant challenge is the need to learn GDScript, which is
22+
often their first exposure to computer programming.
23+
24+
The block coding plugin aims to make game creation in Godot much easier
25+
to achieve for those learners, by postponing or eliminating the need to learn
26+
computer programming & GDScript. Those learners can first focus their
27+
attention on learning their way around the Godot editor, node types,
28+
inspector properties, animations, etc. without the simultaneous additional
29+
burden of having to learn programming.
30+
31+
## Learning tool
32+
33+
This plugin is intended to be used as a learning tool. The intended audience
34+
consists of aspiring game creators that are getting started in Godot, and
35+
have limited or no computer programming experience.
36+
37+
Block coding is not intended to be a replacement for GDScript. We anticipate
38+
that there will things that are infeasible to achieve with block programming,
39+
but perfectly possible with GDScript or other advanced programming tools.
40+
41+
We anticipate that once learners have found their bearings in Godot, if they
42+
have enough curiosity and motivation for the coding aspect they will then
43+
progress to learn GDScript and abandon block coding.
44+
45+
That said, we are not against receiving contributions that increase the
46+
scope of what can be achieved with block programming, as long as that
47+
does not detract from the learner experience within our primary audience.
48+
49+
50+
## A layer on top of Godot
51+
52+
We offer block coding as a layer on top of Godot. It does not intend to
53+
deviate far from the typical foundations of 'ordinary' Godot game building.
54+
In order to build games with blocks, you need to understand nodes and scenes,
55+
you need to use the inspector, build tilemaps, etc. The block coding aspect
56+
is aimed to be complementary, we will not attempt to (e.g.) offer an
57+
animation-building block language (we expect the user to learn and
58+
use Godot's standard animation functionality).
59+
60+
This is somewhat contrary to some other block coding environments. Scratch,
61+
for example, seeks primarily to be a highly effective digital creation tool
62+
that embodies the principles of constructionism. As such, they have features
63+
and behaviours that are not feasible or interesting for our tool, e.g.
64+
in Scratch everything is a sprite (there is no hierarchy or typing, every
65+
block works on every sprite), and blocks are live e.g. the program is
66+
constantly running in some sense, you can click on blocks to instantly see
67+
what they do. These features are inherent to Scratch's focus on being the
68+
most powerful digital creation tool around, whereas our block coding
69+
language's inherent focus is on top of the existing norms of the Godot engine.
70+
71+
## Teach Godot concepts, but with natural language
72+
73+
Learners who succeed in using our tool to build games will become familiar
74+
with the concepts of game building with Godot & GDScript, however we prefer
75+
to use natural language for the text on the blocks themselves (e.g. "when
76+
another node collides with this one") rather than Godot's technical terms
77+
(e.g. "on body entered").
78+
79+
We believe the use of natural language provides a much smoother learning
80+
experience, and that if learners later progress to GDScript, they will be
81+
immediately and effortlessly able to recognise that the syntax to do X was
82+
worded as Y in the block language. The important thing is that they have
83+
picked up the underlying concepts through building games with blocks.
84+
85+
## Focus on high level abstraction
86+
87+
Our block language does not intend to mirror GDScript. Instead, we focus on
88+
providing a higher level of abstraction. There's so much value in having
89+
learners being able to very quickly drag and drop just a few blocks and have
90+
a working game. It makes building simple games that much smoother. We want to
91+
trigger a "holy cow, I can actually do this" spark in our learners after just
92+
a few minutes, which will provide the motiviational drive for them to persist
93+
along the challenging journey of mastering Godot.
94+
95+
Compared to GDScript, there are also some things that are just tedious and
96+
boring to do in regular blocks, like displaying a score counter on the
97+
screen. Try creating block code to maintain a score variable which you then
98+
convert to text, embed in a label and show on-screen, it's a bit annoying how
99+
many blocks are involved in that simple operation. So we provide higher level
100+
components that make common things like this dead simple.
101+
102+
Despite our desire to provide fun, easy high level blocks, we do not exclude
103+
the provision of lower level blocks as a secondary goal. For example, we
104+
provide a single ultra simple high-level block that lets you move a sprite
105+
around based on arrow key input, which is heavily inspired by Makecode Arcade's
106+
"move mySprite with buttons" block. However if you wish to calculate a
107+
sprite's movement vector based on keyboard input, and then ask the physics
108+
engine to move things around (as you'd typically do in GDScript), then we have
109+
blocks that let you do that.
110+
111+
## Limited scope of game genres & functionality
112+
113+
Through our focus on learner-suitable high level abstraction instead of
114+
mirroring GDScript, we hit the tradeoff that some capabilities are lost,
115+
you may encounter things that you can't implement in blocks.
116+
117+
We're focused on facilitating creation of 2D games, particularly platformers
118+
and top-down games. We'll try to plug obvious gaps in the block collection and
119+
capabilities as we find them.
120+
121+
We're open to contributions that increase the scope of what can be created
122+
with blocks, as long as it doesn't compromise the learner experience on
123+
those 2D game genres.
124+
125+
## Code generation is not a goal
126+
127+
Internally, our plugin converts block scripts created by the user into
128+
real GDScript. There's a button that lets you see the GDScript code generated
129+
by your blocks.
130+
131+
We regard the code generation as an internal implementation detail that might
132+
go away in future. It is done this way because it was the fastest way to
133+
prototype the block language back when we started the project, and we haven't
134+
yet encountered strong reasons to change it. But we might.
135+
136+
It's nice to think that this functionality could have some value to learners
137+
who later progress onto GDScript. If they can build in blocks and then see
138+
the equivalent GDScript, isn't that going to facilitate the transition?
139+
140+
While there's undoubtedly a little value in that, in reality it is not
141+
as useful as it sounds. A learner's programming journey typically begins
142+
with very trivial programs or carefully orchestrated small code changes, to
143+
avoid being overwhelmed by a larger body of work. Learners benefit most from
144+
high quality, well crafted and nicely formatted code, with associated
145+
documentation and guidance. The internal output of our block coding plugin
146+
does not attempt to provide any of those; we wouldn't advocate showing it
147+
to learners who have never seen code before.
148+

0 commit comments

Comments
 (0)