microsim-p5

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Educational MicroSim Creation Skill for P5.js

基于p5.js的教育类MicroSim创建指南

Overview

概述

This skill guides the creation of Educational MicroSims using the p5.js JavaScript library. MicroSims are lightweight, interactive educational simulations designed for browser-based learning. MicroSims occupy a unique position at the intersection of Simplicity (focused scope, transparent code), Accessibility (browser-native, universal embedding), and AI Generation (standardized patterns, prompt-compatible design).

本指南介绍如何使用p5.js JavaScript库创建教育类MicroSim。MicroSim是专为浏览器端学习设计的轻量级交互式教育模拟程序，它在简洁性（聚焦明确场景、代码透明）、可访问性（原生浏览器支持、可通用嵌入）和AI生成适配性（标准化模式、兼容提示词驱动开发）三者的交叉点上占据独特定位。

Standard Context

标准环境

This MicroSim Skill is designed to create all the required files for running your MicroSim on your website. This microsim skill has been designed to be run within Claude code. The best practice is to startup Claude Code from the command line where you at the root of the GitHub checkout directory. This is one level down from where you ran GitClone. This directory should contain a

.git

directory. If you don't see a

.git

directory and a

mkdocs.yml

file warn the user that the automatic installation process may fail.

We assume that the website has a folder called

docs/sims

that each MicroSim will be placed in. If you do not see this folder then warn the user.

The p5.js file is also designed to that it can be tested by pasting the JavaScript directly into the p5.js editor site at https://editor.p5js.org/. After the JavaScript file has been generated, indicate to the user that the MicroSim can now be tested.

本MicroSim创建指南旨在生成在网站上运行所需的全部文件，且专为在Claude Code中运行设计。最佳实践是从命令行启动Claude Code，且当前工作目录为GitHub仓库的根目录（即执行GitClone命令后进入的下一级目录），该目录应包含

.git

文件夹。如果未找到

.git

文件夹和

mkdocs.yml

文件，请向用户发出警告，提示自动安装过程可能失败。

我们假设网站已存在

docs/sims

文件夹，所有MicroSim都将放置于此。如果未找到该文件夹，请向用户发出警告。

生成的p5.js文件可直接粘贴到p5.js编辑器网站（https://editor.p5js.org/）中进行测试。JavaScript文件生成完成后，请告知用户可开始测试MicroSim。

Purpose

目标

Educational MicroSims transform abstract concepts into visual interactive, manipulable experiences that enable students to learn through exploration and experimentation. Each MicroSim addresses specific learning objectives while maintaining the pedagogical rigor and technical quality necessary for educational deployment.

MicroSims are designed to be referenced by an iframe on an existing website or quickly added to a website or intelligent textbook created with mkdocs. Because MicroSims have strict rules for controls, they can generate xAPI (eXperience API IEEE 9274.1.1-2023) calls so that interaction events in JSON format can be added to a LRS learning Record Store IEEE 1484.20-2024.

教育类MicroSim将抽象概念转化为可视化的交互式可操作体验，让学生通过探索和实验进行学习。每个MicroSim针对特定学习目标，同时保持教育部署所需的教学严谨性和技术质量。

MicroSim可通过iframe引用到现有网站，或快速添加到使用mkdocs创建的智能教材中。由于MicroSim的控件遵循严格规则，它可以生成xAPI（eXperience API IEEE 9274.1.1-2023）调用，将JSON格式的交互事件发送到LRS学习记录存储（IEEE 1484.20-2024）。

Development Process

开发流程

Step 1: Educational Requirements Specification

步骤1：教育需求规范

Before generating code, articulate the educational purpose:

Subject Area and Topic: What specific concept does this simulation teach?
Grade Level: Elementary (K-5), Middle School (6-8), High School (9-12), or Undergraduate
Learning Objectives: What should students know after using this simulation? (Align with Bloom's Taxonomy: Remember, Understand, Apply, Analyze, Evaluate, Create). This step is critical, since the type of p5 MicroSim generated will depend on this classification.
Duration: Typical engagement time (5-15 minutes recommended)
Prerequisites: What knowledge must students have before using this?
Assessment Opportunities: How can educators verify learning? Can the user see a "Quiz Mode" button on this version?

This information will be documented at the end of the index.md file and also stored in a file called metadata.json that is validated by a JSON Schema at https://github.com/dmccreary/microsims/blob/main/src/microsim-schema/microsim-schema.json

在生成代码之前，明确教育目标：

学科领域与主题：本模拟程序教授什么具体概念？
年级水平：小学（K-5）、初中（6-8）、高中（9-12）或本科
学习目标：学生使用本模拟程序后应掌握哪些知识？（需符合布鲁姆分类法：记忆、理解、应用、分析、评估、创造）。这一步至关重要，因为生成的p5 MicroSim类型将取决于此分类。
时长：预计使用时长（建议5-15分钟）
前置知识：学生使用前需具备哪些知识？
评估方式：教育者如何验证学习效果？当前版本是否包含“测验模式”按钮？

以上信息将记录在index.md文件的末尾，同时存储在metadata.json文件中，该文件需符合位于https://github.com/dmccreary/microsims/blob/main/src/microsim-schema/microsim-schema.json的JSON Schema规范。

Step 2: MicroSim Implementation with p5.js

步骤2：使用p5.js实现MicroSim

Generate a self-contained, interactive p5.js simulation following the standardized MicroSim architecture.
The program is width responsive and the p5.js javascript file we create should run without changes using the p5.js editor for easy testing by the user.

遵循标准化MicroSim架构，生成独立可运行的交互式p5.js模拟程序。程序支持宽度自适应，生成的p5.js JavaScript文件无需修改即可在p5.js编辑器中运行，方便用户测试。

Folder Structure

文件夹结构

MicroSims have two properties:

MICROSIM_TITLE: A title case string with spaces
MICROSIM_NAME: A lower-case string with dashes (kebob case)

Each MicroSim is contained in a folder within the /docs/sims directory. The folder name is $MICROSIM_NAME and has the following contents:

/docs/sims/$MICROSIM_NAME # container folder for MicroSim
/docs/sims/$MICROSIM_NAME/index.md # main index markdown for each MicroSim containing the iframe and documentation
/docs/sims/$MICROSIM_NAME/main.html # main HTML5 file containing the p5.js CDN link and importing the p5.js JavaScript
/docs/sims/$MICROSIM_NAME/$MICROSIM_NAME.js # All the p5.js JavaScript
/docs/sims/$MICROSIM_NAME/metadata.json # JSON file with Dublin core metadata and description of controls

The following steps are an example of generating a new MicroSim within a checked out intelligent textbook built with mkdocs. This skill contains templates for the

index.md

main.html

metadata.json

and a

bouncing-ball.js

A new folder will be created inside the
```
/docs/sims
```
area. The folder name contains only lower case letters and dashes. This will be the MICROSIM_NAME which is the kebab case string.
An
```
index.md
```
file will be generated in the folder that describes the MicroSim and contains in iframe reference to the
```
main.html
```
file
A small
```
main.html
```
file will contain the title, link to the p5.js library from the CDN and include the MICROSIM_NAME.js file. The
```
main.html
```
file must contain a
```
main
```
HTML element within the body.
A file called
```
metadata.json
```
will be created that conforms to the schema at /src/microsim-schema/microsim-schema.json. This will contain the Dublin core elements such as title, subject, author, publication date etc. This file is use so that faceted search engines can find this MicroSim

每个MicroSim包含两个属性：

MICROSIM_TITLE：标题格式的字符串（包含空格）
MICROSIM_NAME：小写字符串，使用短横线分隔（kebab case）

每个MicroSim都包含在/docs/sims目录下的一个文件夹中，文件夹名为$MICROSIM_NAME，包含以下内容：

/docs/sims/$MICROSIM_NAME # MicroSim的容器文件夹
/docs/sims/$MICROSIM_NAME/index.md # 每个MicroSim的主索引markdown文件，包含iframe引用和文档说明
/docs/sims/$MICROSIM_NAME/main.html # 主HTML5文件，包含p5.js CDN链接并导入p5.js JavaScript文件
/docs/sims/$MICROSIM_NAME/$MICROSIM_NAME.js # 所有p5.js JavaScript代码
/docs/sims/$MICROSIM_NAME/metadata.json # 包含Dublin Core元数据和控件说明的JSON文件

以下步骤是在已检出的mkdocs智能教材中生成新MicroSim的示例。本指南包含

index.md

、

main.html

、

metadata.json

和

bouncing-ball.js

的模板。

在
```
/docs/sims
```
目录下创建新文件夹，文件夹名仅包含小写字母和短横线，即MICROSIM_NAME（kebab格式字符串）。
在该文件夹中生成index.md文件，描述MicroSim并包含对main.html文件的iframe引用。
生成小型main.html文件，包含标题、指向p5.js库的CDN链接，并引入MICROSIM_NAME.js文件。main.html文件的body中必须包含一个
```
main
```
HTML元素。
创建符合/src/microsim-schema/microsim-schema.json规范的metadata.json文件，包含title、subject、author、publication date等Dublin Core元素，供分面搜索引擎查找该MicroSim。

Technical Architecture Standards

技术架构标准

Iframe Structure (REQUIRED)

Iframe结构（必填）

MicroSims are designed to be called by an HTML

iframe

. They run in a fixed height region with a variable width. This is an essential requirement and it will impact many design choices you make when generating a MicroSim.

Although the main.html file may have some text outside the

<main></main>

element such as a link to return to the documentation, this text is minimal so the area taken by the

iframe

within a textbook is minimized. Putting headers above the

<main></main>

takes away from the ability to reuse the microsim in many educational contexts where management of screen real-estate is critical.

Here is an example of how a MicroSim is integrated into any course webpage:

html

<iframe src="https://dmccreary.github.io/microsims/sims/[MICROSIM_NAME]/main.html" height="500pt" width="100%" scrolling="no"></iframe>

The documentation page (index.md) will provide a sample of this iframe statement that makes it easy for the user to copy.

All iframes that enclose a MicroSim are designed to be run in the entire width of their container and non-scrolling. This prevents confusion to the user that sees scrolling regions with scrolling regions of a web page.

Every MicroSim must have two distinct regions of the

iframe

canvas:

A top
```
drawing
```
region with a fixed height called
```
drawHeight
```
. No user interface controls are placed in the drawing region.
A user interface
```
controls
```
region below the drawing region that contains buttons and sliders with a fixed height called
```
controlHeight
```
.

The width of the canvas is resized according to the container. It is set initially, but reset in the draw loop when the container has changed. This resize function is called every time the web browser window is resized.

We use this layout pattern:

javascript

// Canvas dimensions - REQUIRED structure
let canvasWidth = 400;              // Initial width (responsive)
let drawHeight = 400;                // Drawing/simulation area height
let controlHeight = 50;              // Controls area height
let canvasHeight = drawHeight + controlHeight;
let margin = 25;                     // Margin for visual elements
let sliderLeftMargin = 105;          // Left margin for slider positioning.  This is the sum of the horizontal size of the largest label and value.
let defaultTextSize = 16;            // Base text size

function setup() {
  updateCanvasSize(); // this gets the width of the container we are running in
  const canvas = createCanvas(canvasWidth, canvasHeight);
  canvas.parent(document.querySelector('main'));

  // Create sliders and controls here
  // Position controls relative to drawHeight

  describe('Educational description for screen readers', LABEL);
}

function draw() {
  updateCanvasSize();
  // Drawing area (light blue background)
  fill('aliceblue');
  rect(0, 0, width, drawHeight);

  // Control area (white background)
  fill('white');
  rect(0, drawHeight, width, controlHeight);

  // Place the title in the top center of the canvas
  fill('black');
  textSize(36); // larger font for the title
  textAlign(CENTER, TOP);
  noStroke();
  text('Title of MicroSim', canvasWidth/2, margin);
  // return default setting to avoid bugs in the main drawing code
  stroke();
  textAlign(LEFT, CENTER);
  textSize(defaultTextSize);

  // main drawing code here

  // Draw control labels and values here in the controls areal

}

Note that every MicroSim should have a title centered at the top.

MicroSim设计为通过HTML

iframe

调用，在固定高度区域运行，宽度可自适应。这是一项核心要求，将影响你在生成MicroSim时的多项设计选择。

尽管main.html文件可在

<main></main>

元素外包含少量文本（如返回文档的链接），但此类文本应尽量精简，以减少MicroSim在教材中占用的iframe区域。在

<main></main>

上方添加标题会降低MicroSim在屏幕空间管理要求严格的教育场景中的复用性。

以下是MicroSim集成到课程网页的示例：

html

<iframe src="https://dmccreary.github.io/microsims/sims/[MICROSIM_NAME]/main.html" height="500pt" width="100%" scrolling="no"></iframe>

文档页面（index.md）将提供该iframe语句的示例，方便用户复制使用。

所有嵌入MicroSim的iframe都设计为占满容器的整个宽度且不滚动，避免用户在网页的滚动区域内看到嵌套的滚动区域，造成混淆。

每个MicroSim的iframe画布必须包含两个独立区域：

顶部的
```
绘图
```
区域，高度固定为
```
drawHeight
```
，该区域不放置任何用户界面控件。
绘图区域下方的用户界面
```
控件
```
区域，包含按钮和滑块，高度固定为
```
controlHeight
```
。

画布的宽度会根据容器大小调整，初始时设置固定值，但在容器大小变化时会在draw循环中重置。每次浏览器窗口大小改变时，都会调用此调整函数。

我们使用以下布局模式：

javascript

// 画布尺寸 - 必填结构
let canvasWidth = 400;              // 初始宽度（自适应）
let drawHeight = 400;                // 绘图/模拟区域高度
let controlHeight = 50;              // 控件区域高度
let canvasHeight = drawHeight + controlHeight;
let margin = 25;                     // 视觉元素边距
let sliderLeftMargin = 105;          // 滑块定位的左侧边距，为最大标签和值的水平尺寸之和
let defaultTextSize = 16;            // 基础文本大小

function setup() {
  updateCanvasSize(); // 获取当前运行容器的宽度
  const canvas = createCanvas(canvasWidth, canvasHeight);
  canvas.parent(document.querySelector('main'));

  // 在此处创建滑块和控件
  // 相对于drawHeight定位控件

  describe('供屏幕阅读器使用的教育描述', LABEL);
}

function draw() {
  updateCanvasSize();
  // 绘图区域（浅蓝色背景）
  fill('aliceblue');
  rect(0, 0, width, drawHeight);

  // 控件区域（白色背景）
  fill('white');
  rect(0, drawHeight, width, controlHeight);

  // 在画布顶部居中位置放置标题
  fill('black');
  textSize(36); // 标题使用更大字号
  textAlign(CENTER, TOP);
  noStroke();
  text('MicroSim标题', canvasWidth/2, margin);
  // 恢复默认设置，避免主绘图代码出现bug
  stroke();
  textAlign(LEFT, CENTER);
  textSize(defaultTextSize);

  // 主绘图代码

  // 在控件区域绘制控件标签和值

}

注意，每个MicroSim都必须在顶部居中位置显示标题。

Responsive Design (REQUIRED)

自适应设计（必填）

Implement horizontal responsiveness for embedding in various platforms:

javascript

function windowResized() {
  updateCanvasSize();
  resizeCanvas(canvasWidth, canvasHeight);
}

function updateCanvasSize() {
  const container = document.querySelector('main');
  if (container) {
    canvasWidth = container.offsetWidth;
    // Reposition all controls to match new width
    // all horizontal sliders much be resized when the container size changes
    if (typeof speedSlider !== 'undefined') {
      // update the size of the slider
      speedSlider.size(canvasWidth - sliderLeftMargin - margin);
    }
  }
}

实现水平自适应，以适配不同平台的嵌入需求：

javascript

function windowResized() {
  updateCanvasSize();
  resizeCanvas(canvasWidth, canvasHeight);
}

function updateCanvasSize() {
  const container = document.querySelector('main');
  if (container) {
    canvasWidth = container.offsetWidth;
    // 重新定位所有控件以匹配新宽度
    // 当容器大小变化时，所有水平滑块必须调整尺寸
    if (typeof speedSlider !== 'undefined') {
      // 更新滑块尺寸
      speedSlider.size(canvasWidth - sliderLeftMargin - margin);
    }
  }
}

Visual Design Standards

视觉设计标准

Color Scheme:

Drawing area background:
```
'aliceblue'
```
Control area background:
```
'white'
```
Borders:
```
'silver'
```
, 1px width
Interactive elements: Use high-contrast, colorblind-safe colors

Typography:

Try to avoid using any text smaller than 16pt. We want the MicroSim text to be readable from the back of the classroom.

Default title size: 36px
Default text size: 16px
Control labels: Bold, positioned consistently in the control region
Value displays: Show current parameter values

配色方案：

绘图区域背景：
```
'aliceblue'
```
控件区域背景：
```
'white'
```
边框：
```
'silver'
```
，1px宽度
交互元素：使用高对比度、适合色弱人群的颜色

排版：

尽量避免使用小于16pt的文本，确保MicroSim文本在教室后排也能清晰阅读。

默认标题大小：36px
默认文本大小：16px
控件标签：加粗，在控件区域内位置统一
值显示：显示当前参数值

Control Patterns

控件模式

Horizontal Sliders In Control Region (for continuous parameters):

Sliders are create with min, max, default and step parameters.

They are then placed below the drawHeight and X over at the sliderLeftMargin. The width of the slider is controlled by the size method and spans the width of the canvas less the sliderLeftMargin - 15;

控件区域的水平滑块（用于连续参数）：

滑块使用min、max、default和step参数创建。

滑块放置在drawHeight下方，X轴位置为sliderLeftMargin。滑块宽度由size方法控制，跨度为canvasWidth减去sliderLeftMargin再减15。

Slider Initialization

滑块初始化

Sliders are created in the

setup()

function. All sliders are horizontal sliders.

javascript

speedSlider = createSlider(0, 20, 3, 0.1);
speedSlider.position(sliderLeftMargin, drawHeight + 15);
speedSlider.size(canvasWidth - sliderLeftMargin - 15);
speedSlider.input(resetSimulation);

Do not use the

style

method to change the width of a slider. Only use the `size' method.

滑块在

setup()

函数中创建，所有滑块均为水平滑块。

javascript

speedSlider = createSlider(0, 20, 3, 0.1);
speedSlider.position(sliderLeftMargin, drawHeight + 15);
speedSlider.size(canvasWidth - sliderLeftMargin - 15);
speedSlider.input(resetSimulation);

不要使用

style

方法更改滑块宽度，仅使用

size

方法。

Slider Width Responsive Behavior

滑块宽度自适应行为

All horizontal sliders must have their width recalculated using the

size

if the container width changes.

当容器宽度变化时，所有水平滑块必须使用

size

方法重新计算宽度。

Slider Label Value Placement

滑块标签与值的位置

At the end of the

draw()

function the label and values for the sliders must be updated. They should be placed with a fixed x offset value around 10. The label and value are concatenated together using the JavaScript "+" operator. Each row of label/value/slider controls should be placed below the prior row by 30.

javascript

text('Speed: ' + speed, 10, drawHeight+20);
text('Angle: ' + angle, 10, drawHeight+50);

在

draw()

函数末尾，必须更新滑块的标签和值。标签和值应放置在固定的X偏移位置（约10px处），使用JavaScript的"+"运算符将标签和值拼接在一起。每行标签/值/滑块控件应比上一行向下偏移30px。

javascript

text('Speed: ' + speed, 10, drawHeight+20);
text('Angle: ' + angle, 10, drawHeight+50);

Buttons for Starting and Pausing a Simulation

用于启动和暂停模拟的按钮

For example if a simulation has a state global variable

isRunning

the button can be created like this:

Buttons (for discrete actions):

javascript

startButton = createButton(isRunning ? 'Pause' : 'Start');
startButton.position(10, drawHeight + 15);
startButton.mousePressed(toggleSimulation);

例如，如果模拟有一个全局状态变量

isRunning

，按钮可按如下方式创建：

按钮（用于离散操作）：

javascript

startButton = createButton(isRunning ? 'Pause' : 'Start');
startButton.position(10, drawHeight + 15);
startButton.mousePressed(toggleSimulation);

Use Checkboxes to Show Additional Optional Information

使用复选框显示额外可选信息

Checkboxes (for toggle options):

javascript

showGridCheckbox = createCheckbox('Show Grid', false);
showGridCheckbox.position(10, drawHeight + 15);

复选框（用于切换选项）：

javascript

showGridCheckbox = createCheckbox('Show Grid', false);
showGridCheckbox.position(10, drawHeight + 15);

main.html

Our goal is to maintain full compatibility with the p5.js editor. JavaScript code generated should always be paste directly into the p5.js editing tool. This tool uses a standard main.html file that contains a '<main></main>` element that holds our canvas. Here is the main.html template that we recommend using:

html

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>$SIMULATION_NAME MicroSim using P5.js 1.11.10</title>
    <script src="https://cdn.jsdelivr.net/npm/p5@1.11.10/lib/p5.js"></script>
    <style>
        body {
            margin: 0px;
            padding: 0px;
            font-family: Arial, Helvetica, sans-serif;
        }
    </style>
    <!-- Put your script file name here -->
    <script src="bouncing-ball.js"></script>
</head>
<body>
    <main></main>
    <br/>
    <a href=".">Back to Documentation</a>
</body>
</html>

我们的目标是保持与p5.js编辑器的完全兼容性，生成的JavaScript代码应可直接粘贴到p5.js编辑工具中使用。该工具使用标准的main.html文件，其中包含一个容纳画布的'<main></main>'元素。以下是我们推荐使用的main.html模板：

html

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>$SIMULATION_NAME MicroSim using P5.js 1.11.10</title>
    <script src="https://cdn.jsdelivr.net/npm/p5@1.11.10/lib/p5.js"></script>
    <style>
        body {
            margin: 0px;
            padding: 0px;
            font-family: Arial, Helvetica, sans-serif;
        }
    </style>
    <!-- 在此处填写你的脚本文件名 -->
    <script src="bouncing-ball.js"></script>
</head>
<body>
    <main></main>
    <br/>
    <a href=".">返回文档</a>
</body>
</html>

Customizing the main.html File

自定义main.html文件

The following items must be modified in each main.html file:

The pathname to the JavaScript file should be modified to use the name of the JavaScript file in the MicroSim directory.
The title element in the body must be modified for each MicroSim.
The version number in the CDN path should only be changed if there are problems running the code.

Note that for label placement in the control area, we set both the margin and padding to be 0. We do not use a separate CSS file. This keeps our code simpler.

每个main.html文件必须修改以下内容：

JavaScript文件的路径应修改为MicroSim目录中的JavaScript文件名。
body中的title元素必须为每个MicroSim修改。
仅当代码运行出现问题时，才修改CDN路径中的版本号。

注意，为了控件区域的标签定位，我们将margin和padding均设置为0，不使用单独的CSS文件，以保持代码简洁。

P5.js Version Updates

P5.js版本更新

Note that this template uses the jsdelivr.net CDN to get the main p5.js library. The version number is hard-coded in this path. If bugs are found one suggestion is to verify that this library is the current one used in the p5.js editor. The following Python code will return the latest version of p5.js.

https://github.com/dmccreary/microsims/blob/main/src/p5-version/p5-version.py

Note that in August of 2026 the default version of p5.js will be 2.x.

注意，本模板使用jsdelivr.net CDN获取p5.js主库，版本号硬编码在路径中。如果发现bug，建议验证该库是否为p5.js编辑器当前使用的版本。以下Python代码可获取p5.js的最新版本：

https://github.com/dmccreary/microsims/blob/main/src/p5-version/p5-version.py

注意，到2026年8月，p5.js的默认版本将为2.x。

Index.md Generation

Index.md生成

A template file

index.md

must be generated for each MicroSim. This file contains metadata in yml format before the header 1 title

必须为每个MicroSim生成模板文件

index.md

，该文件在一级标题前包含yml格式的元数据。

Index.md Metadata

Index.md元数据

yml

---
title: Bouncing Ball
description: A MicroSim of a ball bouncing within the drawing region with a control for changing the speed.
image: /sims/bouncing-ball/bouncing-ball.png
og:image: /sims/bouncing-ball/bouncing-ball.png
twitter:image: /sims/bouncing-ball/bouncing-ball.png
social:
   cards: false
---

Here is an example of the content of the index.md file

markdown

undefined

yml

---
title: Bouncing Ball
description: A MicroSim of a ball bouncing within the drawing region with a control for changing the speed.
image: /sims/bouncing-ball/bouncing-ball.png
og:image: /sims/bouncing-ball/bouncing-ball.png
twitter:image: /sims/bouncing-ball/bouncing-ball.png
social:
   cards: false
---

以下是index.md文件内容的示例：

markdown

undefined

Bouncing Ball

Run the Bouncing Ball MicroSim Fullscreen{ .md-button .md-button--primary } <br/> Edit the Bouncing Ball MicroSim with the p5.js editor

全屏运行Bouncing Ball MicroSim{ .md-button .md-button--primary } <br/> 使用p5.js编辑器编辑Bouncing Ball MicroSim

Description

描述

[Description of the MicroSim]

[MicroSim描述]

Lesson Plan

教案

[Lesson Plan for Using the MicroSim]


In addition, the following sample iframe should be placed before the description.  Make sure to
enclose the HTML in triple grave accent characters.

You can include this MicroSim on your website using the following `iframe`:

```html
<iframe src="https://dmccreary.github.io/microsims/sims/bouncing-ball/main.html" height="432px" scrolling="no"></iframe>

The bouncing ball is the "Hello World!" of the Educational MicroSims. It contains the key elements that shows the power of the width-responsive MicroSims graphics with movement and user interaction. When we design MicroSims, we also want clearly-visible user interface elements in the control area that can control the running of our simulations. This version contains a slider to control the speed of the ball's movement.

[使用MicroSim的教案]


此外，应在描述前添加以下示例iframe代码，确保将HTML代码包裹在三个反引号中。

你可使用以下`iframe`将此MicroSim添加到你的网站：

```html
<iframe src="https://dmccreary.github.io/microsims/sims/bouncing-ball/main.html" height="432px" scrolling="no"></iframe>

弹跳球是教育类MicroSim的"Hello World"示例，它包含了宽度自适应MicroSim图形、运动效果和用户交互等核心元素。在设计MicroSim时，我们还希望控件区域有清晰可见的用户界面元素，用于控制模拟运行。本版本包含一个用于控制小球移动速度的滑块。

Lesson Plan

教案

Both the title and the description should be modified by this SKILL.

These tags are used to create high-quality social media previews when instructors copy the MicroSim links into tools like Zoom chats. The .png image should be created by a human with the same name as the MicroSim. Add are reminder to do this to the user.

标题和描述均需通过本指南进行修改。

这些标签用于当教育者将MicroSim链接复制到Zoom聊天等工具时，生成高质量的社交媒体预览图。.png图片应由人工创建，名称与MicroSim一致，请提醒用户完成此操作。

Metadata Generation

元数据生成

The MicroSim metadata is stored within the MicroSim folder in a file called

metadata.json

. The structure of this file is governed by a JSON schema file located at /src/microsim-schema/microsim-schema.json.

MicroSim元数据存储在MicroSim文件夹中的metadata.json文件中，该文件的结构由位于/src/microsim-schema/microsim-schema.json的JSON schema文件定义。

Educational Design Principles

教育设计原则

1. Focused Scope

1. 聚焦明确场景

Each MicroSim addresses ONE specific learning objective. Do not attempt to teach an entire topic—focus on a single concept, relationship, or phenomenon that benefits from interactive exploration.

每个MicroSim仅针对一个特定学习目标，不要试图教授整个主题——专注于一个适合交互式探索的单一概念、关系或现象。

2. Immediate Feedback

2. 即时反馈

Students must see the effects of their parameter changes instantly. The simulation should update in real-time as sliders move or buttons are clicked.

学生必须能立即看到参数更改的效果，当滑块移动或按钮点击时，模拟应实时更新。

3. Transparent Implementation

3. 实现透明

Code should be readable and well-commented so educators and advanced students can understand the underlying model. Include comments explaining:

Mathematical equations being modeled
Physical principles being demonstrated
Assumptions and simplifications made

代码应具有可读性且注释完善，以便教育者和高阶学生理解底层模型。注释应包含：

所建模的数学方程
所演示的物理原理
所做的假设和简化

4. Progressive Complexity

4. 渐进式复杂度

Start with simple defaults that demonstrate the core concept. Allow students to increase complexity through parameter manipulation.

从演示核心概念的简单默认设置开始，允许学生通过参数调整增加复杂度。

5. Cognitive Load Management

5. 认知负荷管理

Minimize extraneous cognitive load: Keep interface clean and uncluttered
Optimize germane cognitive load: Focus attention on the educational concept
Support intrinsic complexity: Provide scaffolding for difficult concepts

最小化额外认知负荷：保持界面简洁有序
优化相关认知负荷：将注意力集中在教育概念上
支持内在复杂度：为复杂概念提供脚手架支持

Example Learning Objectives by Domain

各领域学习目标示例

Physics & Engineering

物理与工程

Demonstrate relationship between force, mass, and acceleration
Visualize wave interference patterns
Explore conservation of energy in colliding objects
Show effects of gravity on projectile motion

演示力、质量和加速度之间的关系
可视化波的干涉图案
探索碰撞中的能量守恒
展示重力对抛体运动的影响

Chemistry & Molecular Science

化学与分子科学

Visualize molecular bonding and bond angles
Demonstrate gas laws (pressure, volume, temperature relationships)
Show chemical equilibrium and Le Chatelier's principle
Illustrate phase changes at molecular level

可视化分子成键和键角
演示气体定律（压强、体积、温度的关系）
展示化学平衡和勒夏特列原理
从分子层面说明物态变化

Biology & Life Sciences

生物与生命科学

Model population dynamics and predator-prey relationships
Simulate genetic inheritance patterns
Demonstrate cell division processes
Explore ecosystem energy flow

模拟种群动态和捕食者-猎物关系
演示遗传遗传模式
展示细胞分裂过程
探索生态系统能量流动

Mathematics & Computer Science

数学与计算机科学

Explore function transformations (translations, dilations, reflections)
Visualize geometric constructions and proofs
Demonstrate probability distributions
Show algorithmic behavior (sorting, searching, recursion)

探索函数变换（平移、缩放、反射）
可视化几何构造和证明
演示概率分布
展示算法行为（排序、搜索、递归）

Systems Thinking

系统思维

Model feedback loops and causal relationships
Demonstrate stock-and-flow dynamics
Show emergent behavior in complex systems
Explore sensitivity to initial conditions

模拟反馈循环和因果关系
演示存量-流量动态
展示复杂系统中的涌现行为
探索对初始条件的敏感性

HTML Structure (REQUIRED)

HTML结构（必填）

Every MicroSim must be a self-contained HTML file following this structure:

html

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>MicroSim: [Concept Name]</title>
  <script src="https://cdnjs.cloudflare.com/ajax/libs/p5.js/1.7.0/p5.min.js"></script>
  <style>
    body {
      font-family: Arial, sans-serif;
      margin: 0;
      padding: 20px;
      background-color: #f5f5f5;
    }
    main {
      max-width: 800px;
      margin: 0 auto;
    }
    h1 {
      text-align: center;
      color: #333;
    }
  </style>
</head>
<body>
  <main>
    <h1>[Simulation Title]</h1>
  </main>
  <script>
    // MicroSim code here following standardized architecture
  </script>
</body>
</html>

每个MicroSim必须是符合以下结构的独立HTML文件：

html

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>MicroSim: [Concept Name]</title>
  <script src="https://cdnjs.cloudflare.com/ajax/libs/p5.js/1.7.0/p5.min.js"></script>
  <style>
    body {
      font-family: Arial, sans-serif;
      margin: 0;
      padding: 20px;
      background-color: #f5f5f5;
    }
    main {
      max-width: 800px;
      margin: 0 auto;
    }
    h1 {
      text-align: center;
      color: #333;
    }
  </style>
</head>
<body>
  <main>
    <h1>[Simulation Title]</h1>
  </main>
  <script>
    // 遵循标准化架构的MicroSim代码
  </script>
</body>
</html>

Metadata Requirements

元数据要求

For each MicroSim, generate comprehensive metadata following the Educational MicroSim Metadata Schema:

为每个MicroSim生成符合教育类MicroSim元数据Schema的全面元数据：

Dublin Core Elements

Dublin Core元素

Title: Clear, descriptive name
Creator: Author(s) name
Subject: Subject area(s) covered
Description: 2-3 sentence summary
Date: Creation date (YYYY-MM-DD)
Type: "Interactive Simulation"
Format: "text/html"
Language: "en" (or appropriate language code)
Rights: License information (e.g., "CC BY 4.0")

Title：清晰、描述性的名称
Creator：作者姓名
Subject：涵盖的学科领域
Description：2-3句话的摘要
Date：创建日期（YYYY-MM-DD）
Type："Interactive Simulation"
Format："text/html"
Language："en"（或相应的语言代码）
Rights：许可信息（例如："CC BY 4.0"）

Educational Metadata

教育元数据

Grade Level: Target age/grade range
Subject Area: Primary subject (Mathematics, Science, etc.)
Topic: Specific topic within subject
Learning Objectives: Bullet list of objectives
Bloom's Taxonomy Levels: Which cognitive levels are addressed
Duration: Estimated engagement time
Prerequisites: Required prior knowledge

Grade Level：目标年龄/年级范围
Subject Area：主学科（数学、科学等）
Topic：学科内的具体主题
Learning Objectives：目标列表（项目符号形式）
Bloom's Taxonomy Levels：涉及的认知水平
Duration：预计使用时长
Prerequisites：所需的前置知识

Technical Metadata

技术元数据

Framework: "p5.js"
Canvas Dimensions: "400×450" (initial)
Responsive: "Width-responsive"
Dependencies: "p5.js CDN"
Accessibility: Features included (keyboard nav, screen reader support)

Framework："p5.js"
Canvas Dimensions："400×450"（初始值）
Responsive："Width-responsive"
Dependencies："p5.js CDN"
Accessibility：包含的功能（键盘导航、屏幕阅读器支持）

User Interface Metadata

用户界面元数据

Controls: List of sliders, buttons, checkboxes with descriptions
Parameters: Each parameter's range, default, purpose

Controls：滑块、按钮、复选框的列表及说明
Parameters：每个参数的范围、默认值和用途

Simulation Model

模拟模型

Model Type: Type of simulation (physics-based, mathematical, agent-based, etc.)
Variables: List of key variables
Equations: Mathematical equations used (if applicable)
Assumptions: Simplifications made for educational purposes
Limitations: What the model does NOT accurately represent

Model Type：模拟类型（基于物理、数学、基于智能体等）
Variables：关键变量列表
Equations：使用的数学方程（如适用）
Assumptions：为教育目的做出的简化
Limitations：模型无法准确表示的内容

Quality Standards

质量标准

Every MicroSim must meet these criteria:

每个MicroSim必须满足以下标准：

Functionality

功能性

✅ Runs without errors in modern browsers (Chrome, Firefox, Safari, Edge)
✅ Responsive design adapts to different container widths
✅ Controls respond immediately to user input
✅ Simulation resets cleanly without page reload

✅ 在现代浏览器（Chrome、Firefox、Safari、Edge）中无错误运行
✅ 自适应设计可适配不同容器宽度
✅ 控件对用户输入响应即时
✅ 模拟可干净重置，无需刷新页面

Educational Quality

教育质量

✅ Addresses specific learning objectives
✅ Provides meaningful interaction (not just animation)
✅ Includes educational context (titles, labels, instructions)
✅ Accurate representation of underlying concept (within stated limitations)

✅ 针对特定学习目标
✅ 提供有意义的交互（而非仅动画）
✅ 包含教育背景（标题、标签、说明）
✅ 准确表示底层概念（在声明的限制范围内）

Code Quality

代码质量

✅ Follows standardized MicroSim architecture
✅ Well-commented and readable
✅ Uses meaningful variable names
✅ Includes
```
describe()
```
function for accessibility

✅ 遵循标准化MicroSim架构
✅ 注释完善、可读性强
✅ 使用有意义的变量名
✅ 包含
```
describe()
```
函数以支持可访问性

Visual Design

视觉设计

✅ Clean, uncluttered interface
✅ Consistent color scheme (aliceblue/white/silver)
✅ High contrast for readability
✅ Professional appearance suitable for classroom use

✅ 简洁、有序的界面
✅ 一致的配色方案（aliceblue/white/silver）
✅ 高对比度以确保可读性
✅ 适合课堂使用的专业外观

Common Patterns and Examples

常见模式与示例

Pattern 1: Parameter Exploration

模式1：参数探索

Students manipulate sliders to see effects on system behavior. Example: Adjust gravity and initial velocity to explore projectile motion.

学生通过操作滑块观察对系统行为的影响。示例：调整重力和初速度以探索抛体运动。

Pattern 2: Comparative Visualization

模式2：对比可视化

Show two scenarios side-by-side for comparison. Example: Compare sorting algorithms (bubble sort vs. quicksort).

并排展示两个场景以便对比。示例：比较排序算法（冒泡排序 vs 快速排序）。

Pattern 3: System Evolution

模式3：系统演化

Observe how a system changes over time, with play/pause/reset controls. Example: Population growth with birth/death rates.

观察系统随时间的变化，包含播放/暂停/重置控件。示例：包含出生率/死亡率的种群增长。

Pattern 4: Interactive Construction

模式4：交互式构建

Students build or modify structures to understand relationships. Example: Construct geometric shapes to explore area/perimeter relationships.

学生构建或修改结构以理解关系。示例：构建几何图形以探索面积/周长关系。

Pattern 5: Data Visualization

模式5：数据可视化

Transform abstract data into visual representations students can manipulate. Example: Interactive histogram showing probability distributions.

将抽象数据转化为学生可操作的可视化表示。示例：展示概率分布的交互式直方图。

Workflow Integration

工作流集成

For Educators Creating MicroSims:

教育者创建MicroSim的流程：

Identify specific learning objective
Describe desired simulation in natural language
AI generates initial implementation following these standards
Educator previews and requests refinements
Metadata generated automatically
Deploy to learning management system via iframe

确定具体学习目标
用自然语言描述所需的模拟
AI遵循本标准生成初始实现
教育者预览并请求优化
自动生成元数据
通过iframe部署到学习管理系统

For Students Extending MicroSims:

学生扩展MicroSim的流程：

Start with existing MicroSim
Modify parameters or add features
Observe how changes affect behavior
Document observations and learning

从现有MicroSim开始
修改参数或添加功能
观察更改对行为的影响
记录观察结果和学习收获

Deployment Considerations

部署注意事项

iframe Embedding (Universal Deployment)

iframe嵌入（通用部署）

MicroSims are designed to be embedded in any web page with a single HTML line:

html

<iframe src="https://dmccreary.github.io/microsims/sims/bouncing-ball/main.html"
        height="432"
        scrolling="no">
</iframe>

For the height, it should be the sum of the drawHeight and the controlHeight plus 2.

MicroSim设计为可通过一行HTML代码嵌入到任何网页：

html

<iframe src="https://dmccreary.github.io/microsims/sims/bouncing-ball/main.html"
        height="432"
        scrolling="no">
</iframe>

高度应设置为drawHeight与controlHeight之和再加2。

Learning Management System Integration

学习管理系统集成

MicroSim should be designed to be easily integrated with any website that supports the HTML

iframe

element.

Compatible with Canvas, Blackboard, Moodle, Google Classroom
No server-side requirements
Works in restricted network environments
Mobile-friendly for tablets and smartphones

MicroSim设计为可轻松集成到任何支持HTML

iframe

元素的网站：

兼容Canvas、Blackboard、Moodle、Google Classroom
无服务器端要求
在受限网络环境中可正常工作
适配平板电脑和智能手机等移动设备

xAPI Integration (Optional)

xAPI集成（可选）

For learning analytics, MicroSims can emit xAPI statements:

Button clicks, slider adjustments
Time spent on task
Parameter exploration patterns
Performance on embedded assessments

对于学习分析，MicroSim可发出xAPI语句：

按钮点击、滑块调整
任务耗时
参数探索模式
嵌入式评估的表现

Pedagogical Context

教学背景

Research Foundation

研究基础

Educational simulations demonstrate consistent benefits:

15-25% improvement in conceptual understanding
30-40% reduction in time to mastery
25-35% increase in student engagement

教育模拟已被证明具有一致的优势：

概念理解提升15-25%
掌握时间减少30-40%
学生参与度提高25-35%

Effective Use Strategies

有效使用策略

Guided Exploration: Provide 2-3 open-ended questions to focus investigation
Predict-Test-Observe: Have students predict before manipulating
Collaborative Learning: Pairs/groups discuss observations
Scaffolded Challenge: Progress from simple to complex parameter spaces

引导式探索：提供2-3个开放式问题以聚焦探究方向
预测-测试-观察：让学生在操作前进行预测
协作学习：小组讨论观察结果
渐进式挑战：从简单到复杂的参数空间逐步推进

Common Pitfalls to Avoid

需避免的常见陷阱

❌ Too many controls (cognitive overload)
❌ Unclear cause-and-effect relationships
❌ Animation without interactivity
❌ Over-simplification that creates misconceptions
❌ Inaccessible interface (poor contrast, no keyboard support)

❌ 控件过多（认知过载）
❌ 因果关系不明确
❌ 仅动画无交互
❌ 过度简化导致误解
❌ 界面不可访问（对比度低、无键盘支持）

Example MicroSim: Bouncing Ball (Physics)

示例MicroSim：弹跳球（物理）

Educational Purpose

教育目标

Demonstrate effects of gravity and elasticity on projectile motion, illustrating energy conservation and loss.

演示重力和弹性对抛体运动的影响，说明能量守恒与损耗。

Learning Objectives

学习目标

Understand relationship between gravitational acceleration and trajectory
Observe energy loss in non-elastic collisions
Apply physics concepts to predict behavior

理解重力加速度与轨迹的关系
观察非弹性碰撞中的能量损失
应用物理概念预测行为

Implementation Highlights

实现要点

javascript

// Core physics model
velocity.y += gravity; // Acceleration due to gravity
position.add(velocity);

// Collision detection and response
if (position.y >= height - radius) {
  position.y = height - radius;
  velocity.y *= -elasticity; // Energy loss on bounce
}

javascript

// 核心物理模型
velocity.y += gravity; // 重力加速度
position.add(velocity);

// 碰撞检测与响应
if (position.y >= height - radius) {
  position.y = height - radius;
  velocity.y *= -elasticity; // 弹跳时的能量损失
}

Controls Provided

提供的控件

Gravity slider (0-2 m/s², default: 0.5)
Elasticity slider (0-1, default: 0.7)
Start/Pause button
Reset button

This example demonstrates all core MicroSim principles: focused scope, transparent physics, immediate feedback, and clean interface.

重力滑块（0-2 m/s²，默认值：0.5）
弹性滑块（0-1，默认值：0.7）
开始/暂停按钮
重置按钮

本示例展示了所有核心MicroSim原则：聚焦明确场景、物理实现透明、即时反馈、界面简洁。

Continuous Improvement

持续改进

Iteration Based on Use

基于使用情况的迭代

Collect feedback from educators and students
Observe which parameters students explore most
Identify common misconceptions revealed by interactions
Refine based on actual classroom use

收集教育者和学生的反馈
观察学生最常探索的参数
识别交互中暴露的常见误解
根据实际课堂使用情况进行优化

AI-Assisted Refinement

AI辅助优化

After initial generation, iteratively improve through prompts like:

"Add a slider to control [parameter]"
"Show the current velocity value"
"Include a graph showing energy over time"
"Add a grid to help students measure distances"

初始生成后，可通过以下提示词进行迭代改进：

"添加一个控制[参数]的滑块"
"显示当前速度值"
"添加一个展示能量随时间变化的图表"
"添加网格以帮助学生测量距离"

Inclusion in the mkdocs Navigation System

纳入mkdocs导航系统

After the files have been created the next step is to include the MicroSim in the mkdocs navigation system. This is done by adding a single line to the

mkdocs.yml

file located in the home directory of the GitHub repository. The mkdocs.yml file contains a

nav

element. Within that there will be a section for all the MicroSims.

yml

nav:
  [text omitted...]
  - MicroSims:
    - List of MicroSims: sims/index.md
    - MicroSim Name 1: sims/name-1/index.md
    - MicroSim Name 2: sims/name-2/index.md

  [text omitted...]

The best practice is to add the new MicroSim you just created at the end of the MicroSims like this:

yml

nav:
  [text omitted...]
  - MicroSims:
    - List of MicroSims: sims/index.md
    - MicroSim Name 1: sims/name-1/index.md
    - MicroSim Name 2: sims/name-2/index.md
    - NEW_MICROSIM_NAME_HERE: sims/name-in-kebab-case/index.md

  [text omitted...]

文件创建完成后，下一步是将MicroSim纳入mkdocs导航系统，这需要在GitHub仓库主目录下的

mkdocs.yml

文件中添加一行代码。mkdocs.yml文件包含

nav

元素，其中有一个所有MicroSim的章节。

yml

nav:
  [省略部分文本...]
  - MicroSims:
    - List of MicroSims: sims/index.md
    - MicroSim Name 1: sims/name-1/index.md
    - MicroSim Name 2: sims/name-2/index.md

  [省略部分文本...]

最佳实践是将新创建的MicroSim添加到MicroSims章节的末尾，如下所示：

yml

nav:
  [省略部分文本...]
  - MicroSims:
    - List of MicroSims: sims/index.md
    - MicroSim Name 1: sims/name-1/index.md
    - MicroSim Name 2: sims/name-2/index.md
    - NEW_MICROSIM_NAME_HERE: sims/name-in-kebab-case/index.md

  [省略部分文本...]

Zip Packaging (Optional)

Zip打包（可选）

By default, a zip package is not created unless the user requests it.

If the users requests "create a package" or "create a zip package", then after you generate a MicroSim with the required files, create a zip file that the user can download. Then return the following instruction:

Congratulations! Your MicroSim zip file has been generated and is ready for testing. The best way to instal this is to run the following commands using the bouncing-ball example:

cd /doc/sims
unzip bouncing-ball.zip

默认情况下，除非用户明确要求，否则不创建zip包。

如果用户要求“创建一个包”或“创建一个zip包”，则在生成包含所需文件的MicroSim后，创建一个可供用户下载的zip文件，然后返回以下说明：

恭喜！你的MicroSim zip文件已生成，可开始测试。最佳安装方式是使用弹跳球示例运行以下命令：

cd /doc/sims
unzip bouncing-ball.zip

Testing Deployment

部署测试

If you are going to test the MicroSim within mkdocs site you can also do the following:

undefined

如果你要在mkdocs站点中测试MicroSim，还可执行以下操作：

undefined

move the zip file out of the way so it does not get copied to the web site

将zip文件移至其他位置，避免被复制到网站

mv bouncing-ball.zip /tmp

edit the mkdocs.yml file

编辑mkdocs.yml文件

open ../../mkdocs.yml

test your code locally

本地测试代码

mkdocs serve

go to the right link: http://localhost:8000/[GITHUB_DIR_NAME]/sims/[sim-name]/

访问正确链接：http://localhost:8000/[GITHUB_DIR_NAME]/sims/[sim-name]/

check in your code with git

使用git提交代码

deploy your new microsim to production!

将新的microSim部署到生产环境！

mkdocs gh-deploy


Then make sure that the site navigation (mkdocs.yml) file includes the link to this new MicroSim.

mkdocs gh-deploy


然后确保站点导航文件（mkdocs.yml）包含指向此新MicroSim的链接。

Conclusion

结论

Educational MicroSims represent a powerful convergence of pedagogical effectiveness, technical accessibility, and AI-generation capability. By following these standards, any educational concept that benefits from interactive exploration can be transformed into a high-quality, embeddable, reusable learning tool.

The key is maintaining focus: one concept, clear interactions, immediate feedback, transparent implementation. Each MicroSim should feel carefully crafted, pedagogically sound, and ready for deployment in real educational contexts.

For Anthropic Claude Code: When creating MicroSims, always reference the comprehensive rules in

.cursor/rules/microsims.mdc

and follow the metadata schema in

src/microsim-schema.json

. Each MicroSim should feel like a polished educational tool developed by expert instructional designers and developers working at the top of their field.

教育类MicroSim代表了教学有效性、技术可访问性和AI生成能力的强大融合。通过遵循本标准，任何适合交互式探索的教育概念都可转化为高质量、可嵌入、可复用的学习工具。

关键在于保持聚焦：一个概念、清晰的交互、即时反馈、透明的实现。每个MicroSim都应经过精心设计，符合教学要求，并可直接部署到实际教育场景中。

Anthropic Claude Code使用说明：创建MicroSim时，请始终参考

.cursor/rules/microsims.mdc

中的完整规则，并遵循

src/microsim-schema.json