Learn World Models: a VitePress course that teaches world models by making you build one

Who the Learn World Models course is written for

The problem this repository addresses is orientation. World-model research spans state estimation, latent dynamics, planning and evaluation, and a reader arriving from a transformers background has no obvious order in which to meet those ideas. Learn World Models answers with a fixed sequence: five lectures (L01 to L05) and six projects (P01 to P06), laid out in a table in the README with core topics per row. L01 defines working interfaces and a capability taxonomy; L02 moves from partial observability and belief state through VAE, GRU, MDN-RNN and RSSM to free rollouts; L03 covers planning and control, backbone selection and nine architecture families; L04 is diagnosis; L05 is frontier debate.

The intended reader is a deep-learning practitioner, not a beginner. The README describes the lecture pages as "concept-first explanations with mermaid diagrams and background callouts for deep-learning readers", which is a fair statement of the assumed baseline: you should be comfortable with autoencoders and recurrent networks before L02 lands. The curriculum flow table makes the dependency explicit by pairing each reading with a practice step, and it closes with a line worth quoting because it sets the tone of the whole project: "You do not need to finish all theory before starting a project. Build, then come back with questions."

Who it is not for: someone who wants a pip-installable world-model package, or a reader who needs a polished, frozen textbook. The README carries an alpha preview caution stating that content is still being completed and revised and that sections, examples and wording may continue to change.

How the course is built: VitePress, three languages, and an external PyTorch tree

The mechanism is a static documentation site, not a runtime system. The repository layout shows a docs/ directory containing a VitePress configuration at docs/.vitepress/config.mts that defines navigation and sidebar for English, Chinese and Korean, with parallel lecture and project directories under docs/en/, docs/zh/ and docs/ko/. Each language carries five lecture modules and six project pages, so the content is maintained in triplicate, and the contributing notes require EN/ZH sync.

Two pieces sit outside the docs tree. The first is external/world-model-tutorial/, described in the README as "PyTorch source referenced by projects", with a references.md holding a four-era history and architecture survey. That is where the runnable training code lives; the project pages reference it rather than embedding everything. The second is scripts/, which holds build utilities for screenshots and PDF export.

The build pipeline is TypeScript end to end. package.json shows a notebooks:render script running tsx scripts/build-notebook-pages.ts, and both build and docs:build run that render step before vitepress build docs. Markdown rendering pulls in markdown-it-mathjax3 for math and mermaid plus vitepress-plugin-mermaid for diagrams, with playwright and pdf-lib used for screenshot capture and PDF generation. The practical consequence: adding a lecture means editing Markdown, and adding a runnable notebook means going through the render script, not dropping a file into docs/ and hoping.

Installing the site and running your first build

The README gives a quick start of four commands. Clone the repository, then install dependencies at the root, where package.json declares vitepress, mermaid, tsx, playwright, typescript and the rest as devDependencies.

npm install
npm run docs:dev        # dev server with hot reload
npm run docs:build      # production build
npm run docs:preview    # preview built site

The first command installs the toolchain. The second starts the local documentation server with hot reload, and you should see the course home in the browser with lecture and project cards. The third produces the production build, and the fourth serves that build locally for a check before publishing.

The README also documents a two-step path for refreshing the README screenshots after a build, which is useful if you fork the project and change the UI.

npm run docs:build
npm run screenshots:readme

Note that docs:build is not a bare VitePress call: package.json defines it as npm run notebooks:render && vitepress build docs, so the notebook pages are regenerated first. If the render step fails, the site build never starts, and that is the first place to look when a build breaks. The published course is also readable without installing anything, at the homepage listed in the repository.

The six projects are where the actual world-model work happens

The lecture track is reading; the project track is the substance. P01 trains a small CNN VAE on 64x64 pixels with an ELBO loss curve and a latent slider visualization. P02 builds an RSSM dynamics model and compares GRU, MDN-RNN and RSSM with prior versus posterior rollout plots. P03 is the full Dreamer loop: encoder plus RSSM plus latent actor-critic on a small pixel environment. P04 swaps the dynamics backbone for a small causal Transformer described as STORM-style and asks you to compare architectures. P05 is an evaluation dashboard collecting FID, reward correlation, PSNR and latent drift per model. P06 is counterfactual, action-conditioned: interventional and counterfactual rollouts, inverse-dynamics regularization and an action-influence metric.

That progression is the strongest argument for the project. P05 and P06 in particular target the part of world-model work that tutorials usually skip, which is judging whether a learned model is any good and whether it responds correctly to actions it has not seen. The evaluation dashboard is a comparison harness rather than a leaderboard, and the counterfactual project is explicitly interventional, which puts it closer to causal probing than to reconstruction quality.

The trade-off is depth per project. Six projects across representation, dynamics, control, backbone choice, evaluation and counterfactuals means each gets a page and a referenced PyTorch source rather than a full research codebase. Expect the projects to be guided exercises, and expect to read external/world-model-tutorial/ to understand what the code actually does.

Limitations: alpha status, licence ambiguity and a documentation-only surface

Three constraints matter before you commit time. First, the alpha preview warning is not boilerplate. The README states that content is still being completed and revised and that sections, examples and wording may continue to change, and it invites feedback through Issues. A course whose lecture text can shift under you is awkward if you are assigning it to a cohort on a fixed schedule.

Second, the licence situation is inconsistent. The README badge reads MIT and links to a LICENSE file at the repository root, but the project's licence field is unknown and no LICENSE entry appears in the top-level repository listing. Before reusing lecture text, diagrams or the PyTorch sources in your own material, check the LICENSE file directly. This is not legal advice, just a note that the two signals disagree.

Third, the repository surface is a documentation site plus a referenced tutorial tree, not a maintained library. There are no releases, the version in package.json is 0.1.0, and there is no API to depend on. If you need a world-model implementation to build a product on, this is the wrong tool: you would be adopting a curriculum and then separately owning the code. The project also does not document rollback, migration or versioning policy for the course content, so there is no supported way to pin a lecture to a specific revision beyond pinning the repository commit yourself.

How it compares with a paper-first or notebook-first approach

The obvious alternative is to skip the course and read the primary sources: the Dreamer and RSSM papers, plus a survey, and then work from an existing research codebase. The difference in approach is real. A paper-first path gives you the current state of the field and the reasoning behind each design decision, but it gives you no ordering and no evaluation harness, and you have to assemble the comparison yourself. Learn World Models inverts that: it fixes an order (L01 to L05, P01 to P06), supplies the comparison tables and the diagnostics lecture, and points at a bundled PyTorch tree, at the cost of being a secondary source that is explicitly still being revised.

A second alternative is a notebook-first tutorial series, where each notebook is self-contained and runnable end to end. That is more immediately satisfying and easier to check, but it usually stops at training a model and rarely reaches P05 or P06 territory. The evaluation dashboard and the counterfactual, action-conditioned project are the parts of this curriculum that a typical notebook series does not cover, and they are the reason to pick it over one.

A third comparison is against a general deep-learning curriculum. Those give you the fundamentals but not the world-model-specific vocabulary of belief state, free rollout, prior versus posterior, or action influence. The trade-off is that this project assumes those fundamentals already, so it is a supplement to a deep-learning background, not a replacement for one.

Maintenance, upgrade cost and what the repository asks of contributors

The last push to the default branch was on 2026-09-15, so the repository is current. It is not archived. There are no releases, so there is no versioned upgrade path: you track main or you pin a commit.

The upgrade cost is concentrated in the toolchain. package.json pins vitepress ^1.6.4, mermaid ^11.14.0, tsx ^4.19.0, typescript ^5.7.0, playwright ^1.59.1 and markdown-it-mathjax3 ^4.3.2, all with caret ranges, so a fresh npm install can move those minors. The build runs the notebook render step first, and the screenshot and PDF scripts depend on playwright, which downloads browsers. If you fork the site for your own course, budget for keeping the render script working as VitePress and mermaid move.

Contributing has its own cost. The README directs contributors to CLAUDE.md for the writing style rules that apply to all lecture and project files, listing no em dashes, no linear mermaid diagrams, no arrow-chain prose and EN/ZH sync among others, and states that content not following those rules will be asked to revise before merging. That is stricter than most documentation repositories, and it is the main reason the three language trees stay aligned. If you plan to add a lecture, read CLAUDE.md before writing anything.

Editorial conclusion

Adopt it if you already read PyTorch and want a structured path from latent dynamics to a working Dreamer loop, and you accept that the README labels the build an alpha preview whose sections, examples and wording may change. Do not adopt it as a reference implementation to vendor into production, and do not expect an installable world-model library: the repository ships a VitePress site plus an external PyTorch tutorial tree. Verify first that the lecture and project pages you need are complete in the language you read, that the external/world-model-tutorial sources still run against your PyTorch and CUDA versions, and that the MIT badge in the README matches the LICENSE file at the repository root, since the licence field for the project is not otherwise stated.

Frequently asked questions

Official sources

1. datawhalechina/learn-world-model on GitHub
2. Issues
3. Project website
4. README