fragcolor-xyz / shards-examples Goto Github PK

The website https://euler.color-rise.xyz/problems/ has some examples and tutorials using chainblocks.

• Add a link to it
• Add a section for future external contributions

For example, if you press the "Output" button of Do's documentation example (https://docs.fragcolor.xyz/shards/General/Do/), it is empty:

• Trim the generated output to improve readability

In the image below, the 1st output shows the results trimmed (manually), while the 2nd output shows the original output.

• Go through a few Processing tutorials and analyze how they were written
• View some Processing video tutorials
• Write thoughts down in Google Docs

• Rework the documentation to guide users on using Git Extensions instead of Github Desktop
• Remove the segment on mkdocs

What does "ticked" mean in the documentation for "Branch": https://docs.fragcolor.xyz/shards/General/Branch/

A branch is a child mesh that runs and is ticked when this shard is activated, wires on this mesh will inherit all of the available exposed variables in the activator wire.

There is a redundant variable in the sample code for the yes-no game tutorial (Step 3 - Selecting The Images).

Pitch
As a game creator new to Fragcolor, I want to learn how to program in Shards so that I may be able to write my own Shards scripts for use in my game projects.

Sections - 6

• Introduction - what is code, what is Shards
• Elements of Shards - functions, shards, wires, and mesh
• Anatomy of a Function - data flow, parameters, execution
• Anatomy of shards - data flow, input/output, parameters
• Manipulating data - operations on variables and data structures
• Controlling the flow - overview of operations on wires

Appendices
Appendices have moved to issue #18

Fix incoming links

• Modify the link to this primer in shards-examples readme - This link should now point to the hosted Shards primer document.
• Modify the incoming link for 'stateful function' from .../functions/macros/#defwire - This link should now point to the mention of 'stateful functions' in section Elements of Shards in the primer.

Following issues document the functions and shards covered in this primer:

• #257 - Aliases and details for variable manipulation shards
• #320 - Shards' types
• #323 - Missing and pending Shards functions
• #324 - Alias for Hashed, Await, Once
• #260 - GFX shards

Rendered markdown with currently finished topics here.

Acceptance criteria
A beginner-friendly getting-started guide for programming with Shards (language primer).

• Refine the chapter based on feedback given
• Try to make the examples less complicated while highlighting key points
• Add in a segment for Branch and StepMany

• Add in a page for building the shard API documentation
• Add in a segment explaining the different folders in the documentation repository

Pitch
As a beginner programmer, I want the Snake tutorial to be easy enough to follow, so that I may be able to work through the whole tutorial on my own.

Acceptance criteria

• The language of the tutorial should be easy enough to be understood by beginner programmers
• Complicated programming terms and techniques should be explained in beginner-friendly terms

Additional Context
Also use improvement notes/observations taken a few months back.

• Fix any problematic examples
• Fill the remaining methods (Step / Branch / StepMany / TryMany)

• Fix grammatical and spelling errors
• Add a summary at the end
• Make the instructions more concise
• Add in debugging help

The highlighted variable is not used and therefore should be removed.

After the time is up, the game-over screen is rendered. However, it can be seen that the player's final score is still changing, indicating that the game itself is still running in the background.
The issue can be reproduced by running the full code for the Glod game.

Pitch
As a developer new to the Chainblocks-Examples repository, I want to quickly understand and set it up, so that I may start contributing if interested.

Acceptance criteria
Update this project repository's README file to satisfy the parent Epic's Acceptance Criteria, and additional criteria given below

• Add link to building-chainblocks documentation
• Run a grammar check on the finished text

Additional context
Refer to guidelines at Github, freeCodeCamp, Make a Readme, & Awesome READMEs.

• Review how mkdocs is used to document current documentation
• Follow tutorials / Research mkdocs
• Do a sample tutorial

• Rework the primer so that it is friendly to those unfamiliar with coding
• Focus on rewriting the introduction to Shards and ensure it conveys the idea of Shards clearly
• Fix spelling and grammar mistakes

Describe the bug

Current documentation suggests that "The message to display can be passed to this shard either as a string or as a variable holding a value. In case a variable is passed the shard displays the variable's value.".

This is not intentional, and Msg should only accept rvalues and not variables nor arguments. The documentation should be updated to reflect accordingly once the behaviour of the Msg shard has been rectified

• Shards that use enums for their parameters should have the enums documented down on their API page

• Review the current structure of the documentation pages
• Rework the structure to better cater for different user groups, improve the navigational flow and accessibility

• Example of markdown issue in step 3.6:

• Various markdown issues mainly from step 3 onwards.

• Table of contents is broken for mainly step 5 onwards. E.g. Step 5.6 and 5.7 are missing in the Step 5 page.

• Another example of markdown issue for code snippets (From step 6):

• Write 1st draft of how to build shards tutorial
• Let Shar try to build it following tutorial
• Work on comments/edits

• [] Plan the game design
• [] Implement a working example
• [] Write a tutorial for it

The following code should be added to the full code si far for step 3.6 of the Glod game tutorial.

(LoadTexture "GlodImages/Character1_Jumping_Left.png") = .character-jumping-left
(LoadTexture "GlodImages/Character1_Jumping_Right.png") = .character-jumping-right

3 (-> .character-direction
(Match [0 (-> .character-jumping-left (UI.Image :Scale (float2 0.2)))
1 (-> .character-jumping-right (UI.Image :Scale (float2 0.2)))]
:Passthrough false))

Convert the Snake-2D game into its 3D version using GFX shards.

The two constants total-rounds and max-timer are declared twice at the start of the program in the sample code for the yes-no game tutorial (Step 3 - Outcome).

• [] Discuss with Nico to learn more about the UI shards
• [] Plan a simple game that teaches the core UI shards and how to utilize them

• Buy Dreams
• Review the "Getting Started" and "Logic" tutorials
• Create a Google Docs to consolidate thoughts

Issue 1: In step 4, the value of 310.0 is assigned at first, making the character appear in the middle of the game. A "floor", or boundary is later set at the bottom of the screen so that the character does not fall off the screen. This results in the character starting at the middle of the screen on an invisible platform, jumping, then landing at the bottom of the screen which is a bit odd. In step 5.4, this value is silently changed to 620.0. This value can just be 620.0 from the start

Issue 2: Values 50 and 5 are used for the damage limits.

They are then subsequently overwritten in the later part of the code to use a margin of 120 and 15.

Convert the Shards Primer document into byte-sized (2-3 minute long) video tutorials

• Videos to be hosted on Fragcolor's official YouTube channel
• YouTube video links to be embedded in the Shards Primer on learn.fragcolor.xyz/shards

• Review primer material (5 pages)
• Review "How to build Shards" Tutorial
• Review "Snake" Tutorial
• create google docs to consolidate thoughts on material

Inconsistency in file directory used to load data

In steps 2, 3, 5:

In full sample code:

Pitch
As a programmer learning Chainblocks, I want the Snake tutorial to be free of any obvious grammar errors and typos, so that I may be able to easily follow the tutorial.

Acceptance criteria

• There should be no obvious grammar errors or typos in the text of the tutorial
• The language used in the tutorial should be simple and easy to understand

• Do a quick review on Google's Tech Writing Course

The "Dispatch" shard, likely an alias for what is now known as "Step" is used in the full code for Yes-No tutorial game. The correct shard "Step" is used in prior parts

• Go through the basics of coding
• Brief introduction to the Shards syntax

There are only clear instructions for Windows & Linux: https://docs.fragcolor.xyz/contribute/code/building-shards/

List may not be exhaustive

• Step 4 uses .x and .y variables, where as Step 5 uses .X and .Y
• LoadTexture is used in step 3 when the shard name is load-texture. In subsequent steps, the shard is then renamed to LoadTexture. All should use load-texture to keep to the naming convention (kebab-case)
• Step 5 uses .score in one part of the tutorial, then uses .Score in another

• Add in missing details for the UI related shards
• Add in a guide for creating UI with shards

• Review all the API documentation
• Note down any empty fields/segments
• Rework any segment that is unclear
• Fix grammatical and spelling errors

• Get a clear comprehension of the different flow functions
• Fix the flow for the Yes-No game
• Write a tutorial with images / GIFs to better illustrate the flow concepts

• Add instructions for inheriting the path type
• Add instructions for getting GFX to work on the release build
• Rework the segment on setting up Git to use Git Extension instead of Github for Desktop

Complete the Shards primer appendices.

Appendices - 3

• Appendix A - Developer toolbox : code editor, loading scripts, hot reloading, code debugging, error-handling, unit testing
• Appendix B - Handling multiple wires : WireRunner, Detach, Spawn, Wait, Branch, Pause, Start, Stop, Step etc.
• Appendix C - Working with graphics: GUI/ Windows, GFX, Shaders, composable graphics rendering, etc

Additional Context
This issue is a continuation of the original Shards primer issue, #12

Convert the Snake-2D game text tutorial into a series of byte-sized (2-3 minute long) video tutorials

• Videos to be hosted on Fragcolor's official YouTube channel
• YouTube video links to be embedded in the Snake 2D text tutorial on learn.fragcolor.xyz/snake

• Refine the chapter based on the feedback given
• Add segments on debugging and writing a working program

A Bishi-Bashi-like game to teach users about conditional sentences, arrays, showing images and variables.

• Develop the barebones of the game
• Meeting with Nico/Gio to check syntax for Shards
• Write a tutorial for the making of it

Inconsistency in the code for calling the end-round wire as well as the result of true > .input-received being a Bool output causes the first When shard depicted to have an input type of Bool whereas the second When shard has an input type of None, resulting in an error "Attempted to call an already composed wire with a different input type"

Note: WireBase::verifyAlreadyComposed in wires.cpp in Shards will have to be smarter in identifying wires that can ignore inputs and ignore differences in input types when called again after composition. Separate issue to be raised there

The following code snippet appears in the Glod game tutorial step 7.5. It is not related to the task of the current step and therefore should be removed.