Editing a WebEJS _source.json Model Using Codex

Overview of the workflow

The basic process is:

Existing WebEJS model folder
        ↓
Ask Codex to examine _source.json
        ↓
Describe the required changes
        ↓
Tell Codex to edit only _source.json
        ↓
Import _source.json into Singapore WebEJS https://webejs.iwant2study.org:8000/
        ↓
Check and generate the model manually
        ↓
Export the completed model as a ZIP file

The important distinction is:

• Codex edits the WebEJS source

• WebEJS generates the deployable HTML5 model

The correct filename is:

_source.json

---

Step 1: Start with an existing WebEJS model

Begin with your existing EJS/WebEJS model.

This will normally be either:

1. A complete exported model folder containing _source.json; or

2. A ZIP file exported from WebEJS.

For example:

physics-of-two-cyclists/
├── _source.json
├── index.html
├── scripts/
├── images/
├── css/
└── other model files

If the model is in a ZIP file, extract it first.

For example:

physics-of-two-cyclists.zip

Extract it to:

C:\WebEJS\physics-of-two-cyclists\

Before editing, it is sensible to keep an untouched copy:

physics-of-two-cyclists-original/
physics-of-two-cyclists-working/

You will give Codex access to the working folder.

---

Step 2: Open the model folder in Codex

Open the complete model folder using your preferred Codex environment, such as:

• The ChatGPT-Codex desktop experience https://chatgpt.com/download/

Select the folder containing _source.json.

For example:

C:\WebEJS\physics-of-two-cyclists\
or
C:\Users\weelo\OneDrive\Documents\0iwant2study.org\lookangejss

Do not initially ask Codex to change anything.

First, ask it to understand the model.

---

Step 3: Ask Codex to examine _source.json

Use a prompt such as:

Examine the file _source.json in this WebEJS model.

This is the editable source file for the simulation.

Do not make any changes yet.

Please identify:

1. The main model variables.
2. The initialization code.
3. The evolution or simulation code.
4. The custom functions.
5. The view elements and controls.
6. The code connected to buttons, sliders and input fields.


Give me a concise explanation of how this simulation is structured.

Codex should inspect the actual source rather than relying only on the generated index.html.

At this stage, you are checking whether Codex correctly understands:

• What the simulation does

• Which variables control it

• Which functions update it

• Which interface elements are connected to those functions

• Where the required changes are likely to be made

---

Step 4: Check Codex’s understanding

Read Codex’s explanation before asking it to edit.

For example, Codex may identify:

Variables:
- x1 and x2 control the cyclists' positions.
- v1 and v2 control their speeds.
- t stores the elapsed time.
- running controls the play state.

Functions:
- resetSimulation() restores the initial state.
- updatePositions() advances the cyclists.
- checkCatchUp() detects when both cyclists meet.

View:
- speedSlider1 controls v1.
- speedSlider2 controls v2.
- playButton starts the model.
- resetButton calls resetSimulation().

Check that this matches your understanding of the model.

If Codex has misunderstood a variable or function, correct it before allowing any edits.

For example:

Your explanation is mostly correct, but x2 is the second cyclist's starting
position, not its current position. The current position is cyclist2X.

Re-examine the source using that distinction. Do not edit anything yet.

---

Step 5: Describe the changes you want

Once Codex understands the model, describe the required changes clearly.

A useful structure is:

Purpose:
What educational or functional improvement is required?

Existing behaviour:
What does the model currently do?

Required behaviour:
What should it do after the change?

Interface changes:
What should be added, removed, moved or renamed?

Constraints:
What existing behaviour must remain unchanged?

For example:

I would like the following changes to the simulation.

Purpose:
Help students identify the time and position at which the faster cyclist
catches the slower cyclist.

Existing behaviour:
The two cyclists move, but the model does not clearly identify the catch-up
event.

Required changes:

1. Detect when the faster cyclist catches the slower cyclist.
2. Display the catch-up time.
3. Display the catch-up position.
4. Pause the simulation when the cyclists meet.
5. Place a marker on the position-time graph at the meeting point.
6. Add a message explaining that both cyclists have the same position at
   that instant.
7. Reset all new values and markers when the Reset button is pressed.

Constraints:

- Keep the existing cyclist controls.
- Keep the existing graph.
- Do not remove existing xAPI, scoring or analytics functions.
- Do not rename existing variables unless necessary.
- Do not change unrelated parts of the simulation.

---

Step 6: Explicitly restrict Codex to _source.json

After describing the changes, tell Codex exactly what it is allowed to modify.

Use wording such as:

Make these changes only in _source.json.

Do not edit index.html or any of the generated JavaScript, CSS or HTML files.

Treat _source.json as the authoritative source.

Make the smallest necessary changes and preserve all unrelated code,
variables, functions, metadata and view elements.

Do not remove or rewrite existing xAPI, LTI, scoring or analytics code.

The modified _source.json must remain readable by WebEJS.

This is one of the most important instructions in the workflow.

The exported HTML and JavaScript files are generated outputs. They should not be the main target because you will subsequently regenerate them through WebEJS.

---

Step 7: Ask Codex to make the changes

After the scope is clear, give Codex permission to proceed:

Proceed with the changes.

Edit only _source.json.

After completing the edit:

1. Validate that the file is still valid JSON.
2. Check that all JavaScript stored inside the JSON remains correctly escaped.
3. Check that no duplicate variables, functions or view elements were added.
4. Summarise the changes that were made.
5. Tell me which parts I should inspect after loading the file in WebEJS.

Codex should now edit the actual _source.json file in the working folder.

---

Step 8: Review the changes made by Codex

Before importing the source into WebEJS, review Codex’s change summary or file diff.

Check especially for:

• Unexpected deletion of existing code

• Renamed variables

• Duplicate variables

• Duplicate buttons or view elements

• Broken quotation marks

• Incorrectly escaped JavaScript

• Changes to scoring or analytics functions

• Large rewrites of unrelated sections

• Changes made outside _source.json

You can ask:

Review your completed modification.

Confirm:

1. Which files were changed.
2. That only _source.json was changed.
3. Which existing variables were modified.
4. Which new variables were added.
5. Which functions were modified or added.
6. Which view elements were modified or added.
7. That existing scoring, xAPI, LTI and analytics code was preserved.
8. That the resulting file is valid JSON.
9. That unrelated parts of the source were not changed.

If Codex changed other files, instruct it to undo those changes:

Revert all changes outside _source.json.

Only the changes made inside _source.json should remain.

---

Step 9: Obtain the modified _source.json

Once the changes are satisfactory, use either of your normal approaches.

Approach A: Use only the modified JSON

Take the updated:

_source.json

Then drag, drop or upload it into the Singapore WebEJS editor.

This is the simplest approach when WebEJS only needs the source file and the model does not depend on newly added external images, audio or other assets.

Approach B: ZIP the complete working folder

ZIP the entire model folder after Codex has finished:

physics-of-two-cyclists/
├── _source.json
├── index.html
├── scripts/
├── images/
└── other files

Create:

physics-of-two-cyclists-modified.zip

This approach is useful when you want to preserve the complete folder or when the model has supporting media and resources.

However, the most important edited file remains:

_source.json

---

Step 10: Load _source.json into Singapore WebEJS

Open your Singapore WebEJS editor.

Import or drag the modified _source.json into the editor.

Once it loads, inspect the relevant sections manually.

Check the model variables

Confirm that:

• New variables appear correctly

• Existing variables are still present

• Initial values are correct

• There are no duplicate variable names

• Variable types are appropriate

Check the initialization pages

Confirm that:

• New variables are initialized

• Reset values are correct

• Existing initialization code remains intact

Check the evolution pages

Confirm that:

• The simulation equations remain correct

• Catch-up or collision detection runs at the correct point

• Play and pause behaviour remains correct

• The simulation does not immediately stop because of an incorrect condition

Check the custom functions

Confirm that:

• New functions appear in the correct pages

• Function names match their calls

• Reset functions clear all new values

• Existing xAPI and scoring functions remain present

Check the view

Confirm that:

• New labels, buttons or panels appear

• Existing controls remain connected

• Button actions call the correct functions

• Properties refer to valid model variables

• The layout remains usable

---

Step 11: Preview the model in WebEJS

Use the WebEJS preview or run function.

Test the original behaviour first:

1. Start the simulation.

2. Pause it.

3. Reset it.

4. Move each slider.

5. Change each input field.

6. Check the graph.

7. Check existing scoring or feedback.

8. Check any existing xAPI interactions.

Then test the new behaviour.

For the cyclist example:

1. Set the second cyclist ahead of the first.

2. Give the first cyclist a higher speed.

3. Start the simulation.

4. Check whether the meeting is detected.

5. Check the displayed meeting time.

6. Check the displayed meeting position.

7. Check the graph marker.

8. Check whether the simulation pauses.

9. Press Reset.

10. Confirm that the message and marker disappear.

Also test boundary cases:

• Equal speeds

• Zero speed

• The faster cyclist already ahead

• Both cyclists starting at the same position

• Very high speeds

• Repeated Reset and Play actions

---

Step 12: Return to Codex when something is wrong

If WebEJS loads the source but the model does not behave correctly, return to Codex with specific evidence.

For example:

The modified _source.json loads successfully in WebEJS.

However, when I press Play, the simulation immediately pauses even though
the cyclists have not met.

Please re-examine the catch-up condition in _source.json.

The condition should trigger only when the first cyclist reaches the second
cyclist from behind.

Make the smallest possible correction.

Edit only _source.json.

For a missing interface element:

The source loads successfully, but the catch-up message does not appear in
the view.

Please check whether the new display variable is correctly linked to the
appropriate WebEJS view element.

Make the correction only in _source.json.

For an import failure:

WebEJS cannot read the modified _source.json.

Review the last changes for:

- invalid JSON;
- incorrectly escaped quotation marks;
- incorrectly escaped line breaks;
- malformed JavaScript strings;
- missing commas or brackets.

Repair only _source.json and preserve the intended changes.

Continue the cycle:

Codex edits _source.json
        ↓
Load into WebEJS
        ↓
Preview and test
        ↓
Report problems to Codex
        ↓
Codex corrects _source.json

---

Step 13: Export the completed model manually from WebEJS

Once the source works correctly:

1. Save the model in WebEJS.

2. Generate or export the simulation.

3. Export it as a ZIP file.

4. Extract the exported ZIP for final testing.

5. Open the generated index.html.

6. Check that the final exported version behaves like the WebEJS preview.

Your final workflow is therefore:

1. Start with an existing WebEJS model.
2. Open its folder in Codex.
3. Ask Codex to examine _source.json without editing.
4. Check Codex's understanding of the model.
5. Describe the required changes.
6. Tell Codex to edit only _source.json.
7. Review the changes.
8. Take the modified _source.json.
9. Import it into Singapore WebEJS.
10. Inspect and test the model manually.
11. Return to Codex for corrections when necessary.
12. Use WebEJS to export the final ZIP file manually.

Reusable Codex prompt

Examine the WebEJS model in this folder.

The authoritative editable source is _source.json.

First, inspect _source.json and explain:

- the important model variables;
- initialization code;
- evolution code;
- custom functions;
- view elements;
- button and slider actions;
- scoring, xAPI, LTI or analytics code.

Do not make changes until you understand the existing structure.

I would then like the following changes:

[INSERT THE REQUIRED CHANGES HERE]

After understanding the request, edit only _source.json.

Important constraints:

- Do not edit index.html.
- Do not edit generated JavaScript, HTML or CSS files.
- Do not change unrelated model behaviour.
- Preserve existing variables and functions unless a change is necessary.
- Preserve all scoring, xAPI, LTI and analytics code.
- Avoid unnecessarily renaming existing variables.
- Do not duplicate variables, functions or view elements.
- Keep the source compatible with WebEJS.
- Make the smallest necessary changes.
- Validate that the completed file is valid JSON.

After making the changes, report:

1. The files changed.
2. The variables added or modified.
3. The functions added or modified.
4. The view elements added or modified.
5. Any possible risks.
6. What I should inspect and test after importing _source.json into WebEJS.

Key rule

Codex modifies only _source.json.

Singapore WebEJS reads the modified source, allows manual checking and
generates the final exported ZIP.