Skip to content

docs: add "Build Your First Game" tutorial - #284

Merged
salazarsebas merged 8 commits into
salazarsebas:mainfrom
ayo-ola0710:end-to-end-tutorial
Aug 15, 2026
Merged

docs: add "Build Your First Game" tutorial#284
salazarsebas merged 8 commits into
salazarsebas:mainfrom
ayo-ola0710:end-to-end-tutorial

Conversation

@ayo-ola0710

@ayo-ola0710 ayo-ola0710 commented Jul 25, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

What was done

Added a comprehensive, step-by-step tutorial for new Rust developers onboarding to Cougr and Soroban. This tutorial addresses the Stage 3 onboarding gap identified in the UX strategy by building a complete, tested, and deployable 2D grid game (based on the spawn_and_move pattern).
It explicitly maps ECS primitives (Components, Systems) to Soroban's unique constraints, specifically highlighting instance storage differences, gas costs, and resource limits. It also introduces local testing using GameHarness and Scenario, ending with Stellar CLI deployment instructions.

Close #250
Close #249

@drips-wave

drips-wave Bot commented Jul 25, 2026

Copy link
Copy Markdown

@ayo-ola0710 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

@ayo-ola0710

ayo-ola0710 commented Jul 25, 2026

Copy link
Copy Markdown
Contributor Author

"I have completed the cougr-site setup with the mdBook IA skeleton and the cross-repository sync script!

You can review the repository here: https://github.com/ayo-ola0710/cougr-site And see the live deployed site here: https://ayo-ola0710.github.io/cougr-site/

Let me know if you would like me to transfer ownership of this repository to the organization, or if you prefer to fork it from my account!"

@salazarsebas

salazarsebas commented Jul 27, 2026

Copy link
Copy Markdown
Owner

"I have completed the cougr-site setup with the mdBook IA skeleton and the cross-repository sync script!

You can review the repository here: https://github.com/ayo-ola0710/cougr-site And see the live deployed site here: https://ayo-ola0710.github.io/cougr-site/

Let me know if you would like me to transfer ownership of this repository to the organization, or if you prefer to fork it from my account!"

awesome

@salazarsebas

salazarsebas commented Jul 27, 2026

Copy link
Copy Markdown
Owner

Great tutorial content for #250 — clear steps, good callouts on storage/gas/resource limits, nice that it links out to PATTERNS.md and examples/ at the end.

However, this PR's description says it closes #249, and that part isn't delivered: #249 asks for a cougr-site repo scaffolded with mdBook (6-section IA, a sync mechanism from docs/*.md, placeholder pages). This PR only adds a single markdown file to this repo's docs/start/.

I see you already built that scaffold at https://github.com/ayo-ola0710/cougr-site (book.toml, src/, sync.py). Could you bring that code into a folder inside this monorepo (e.g. cougr-site/) and add it to this PR, so #249's deliverable actually lands here rather than living in a separate, disconnected repo? Once that's folded in, this PR would cover both #249 and #250.

This was referenced Jul 27, 2026
Closed
Closed
@ayo-ola0710

ayo-ola0710 commented Jul 28, 2026

Copy link
Copy Markdown
Contributor Author

@salazarsebas pls review

@salazarsebas

salazarsebas commented Jul 28, 2026

Copy link
Copy Markdown
Owner

The tutorial content itself (docs/start/build-your-first-game.md) looks great and covers #250 well. Separate concern: this PR also commits the full built mdBook output (cougr-site/book/..., ~80 files of generated HTML/fonts/CSS) directly into this repo. Per #249, the docs site is meant to live in its own cougr-site repository that builds from docs/*.md here rather than duplicating/vendoring the built output into this repo. Could you rebase onto main, drop the committed book/ build artifacts from this PR, and split the docs-site scaffolding (#249) into a PR against a separate cougr-site repo? That'd let the tutorial content land cleanly on its own.

@ayo-ola0710
ayo-ola0710 force-pushed the end-to-end-tutorial branch from c1b45aa to 2eb656e Compare July 28, 2026 18:32
@ayo-ola0710

ayo-ola0710 commented Jul 28, 2026

Copy link
Copy Markdown
Contributor Author

@salazarsebas
Thank you for the clarification! I've rebased and dropped the site scaffolding from this PR so it only contains the tutorial content for #250.

For #249, I have the docs-site scaffold fully built in its own separate repository here: https://github.com/ayo-ola0710/cougr-site (it includes the GitHub Action sync mechanism and the mdBook setup). How would you like to proceed with merging that part? Should I transfer ownership of that repository to the organization, or if you want to create an empty salazarsebas/cougr-site repo for you to open a PR against.

@salazarsebas

salazarsebas commented Jul 29, 2026

Copy link
Copy Markdown
Owner

Great tutorial content for #250 — clear steps, good callouts on storage/gas/resource limits, nice that it links out to PATTERNS.md and examples/ at the end.

However, this PR's description says it closes #249, and that part isn't delivered: #249 asks for a cougr-site repo scaffolded with mdBook (6-section IA, a sync mechanism from docs/*.md, placeholder pages). This PR only adds a single markdown file to this repo's docs/start/.

I see you already built that scaffold at https://github.com/ayo-ola0710/cougr-site (book.toml, src/, sync.py). Could you bring that code into a folder inside this monorepo (e.g. cougr-site/) and add it to this PR, so #249's deliverable actually lands here rather than living in a separate, disconnected repo? Once that's folded in, this PR would cover both #249 and #250.

As I told you here, I would like you to solve issue 249 to make a folder here in this same repository and include everything here, please
@ayo-ola0710

@ayo-ola0710

ayo-ola0710 commented Jul 29, 2026

Copy link
Copy Markdown
Contributor Author

@salazarsebas
So, this PR ports the cougr-site documentation directly into the main Cougr repository to centralize our code and docs.

Here is a quick summary of how this was structured:

Created a new cougr-site/ directory at the root of the project to house the documentation.
Ported over the source files: I brought in the src/ directory (which contains all the markdown files), book.toml, sync.py, and .gitignore.
Excluded build artifacts: I intentionally excluded the generated book/ directory from being copied and committed. This ensures we are only tracking the source markdown and keeping the repository history clean from compiled static files.

Is these ok to close the two isses
or do you still want me to create them as two seperate PRs

@salazarsebas

salazarsebas commented Aug 15, 2026

Copy link
Copy Markdown
Owner

Closing — the docs-site portion of this PR (closing #249) scaffolds cougr-site/ inside this repository, but #249 explicitly requires the site to live in its own repository. The tutorial content (closing #250) is valuable and not in question here — please resubmit it once the site repository exists, or as a standalone docs/ addition in the meantime if useful independently of the site scaffold. Reopening #249 for a fresh attempt against the actual requirement.

@salazarsebas salazarsebas mentioned this pull request Aug 15, 2026
Closed
3 tasks
@salazarsebas

salazarsebas commented Aug 15, 2026

Copy link
Copy Markdown
Owner

Reopening — closed earlier for the wrong reason (assumed the docs site needed a separate repository). Confirmed it does not: this repo keeps everything, and the cougr-site/ folder approach here is the one we're moving forward with.

@salazarsebas salazarsebas reopened this Aug 15, 2026
@salazarsebas
fix(docs-site): read source docs from local checkout instead of cloning
a12eaaf 
sync.py cloned salazarsebas/Cougr over the network to read docs/*.md,
which made sense when cougr-site was going to be a separate repository.
Since it now lives in this repo, that clone pulled main instead of the
current checkout, so doc edits in the same PR never made it into the
synced output. Read straight from the local checkout instead.
@salazarsebas
fix(docs-site): drop invalid multilingual key from book.toml
0bf9c2f 
mdbook rejects this field entirely (unknown field, expected one of
title/authors/description/src/language/text-direction), so the site
never built. Also drops the leftover .tmp-source/ gitignore entry now
that sync.py no longer clones into a temp directory.
@salazarsebas
ci(docs-site): build cougr-site and check it stays in sync
dfbe576 
Runs sync.py against the checkout and fails if it produces a diff, so
a doc edit that isn't reflected in cougr-site/src gets caught instead
of silently drifting. Also runs mdbook build to catch a broken config
or IA before merge.
@salazarsebas
fix(docs-site): re-sync build-your-first-game.md from its source
659b342 
The committed copy in cougr-site/src was a 16-line stub; docs/start/build-your-first-game.md
has the real 261-line tutorial. Running the corrected sync.py brings
cougr-site/src back in line with the source of truth.
@salazarsebas
Merge remote-tracking branch 'origin/main' into pr-284-clean
5de0587
@salazarsebas
chore(docs-site): re-sync content with latest main
b659827 
Several docs (ARCHITECTURE.md, PATTERNS.md, PERFORMANCE.md, CHANGELOG.md,
CONTRIBUTING.md) and three new ADRs landed on main after this branch was
created. Re-running sync.py brings cougr-site/src back in line.
salazarsebas
salazarsebas approved these changes Aug 15, 2026
View reviewed changes

@salazarsebas salazarsebas left a comment

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@salazarsebas
salazarsebas merged commit a8204fe into salazarsebas:main Aug 15, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@salazarsebas salazarsebas salazarsebas approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

2 participants

@ayo-ola0710 @salazarsebas