Equations

A little program for practicing equations.

The program creates equations, lets the user solve them and check their answers, and keeps a score. There are also levels, where the user gets progressively more complicated equations, and every few equations the user gets one from one level above (a "challenge").

Development notes

Development happens on branch main. Commits there that pass CI are built and deployed in branch production by GitHub Actions.

To add new levels, go to src/js/levels. Levels are tested for solvability in levels.test.ts; by default we test the first 500 assignments for each level; to test more, run something like this:

SOLVABILITY_ITERATIONS=10000 jest tests/levels.test.ts

todo:

• give extra score for verified steps towards solution? (level is 10, step is 1?)

• give 3-1 stars (score points) for first-third attempt? should score be given only if answered within a given number of attempts?

• keep time better?

  • first, evaluate how long measured pauses are
  • time counting only with keystrokes? pause after half a minute without a keystroke?
  • maybe later award extra type of point (not counted but showing) for being within some time.

• add tutorial levels

  • get played before the first challenge of a given level
  • any level has a link to its tutorial level
  • don't allow the user to make assignment 4 in a batch a challenge if winning it would lead to leveling up
  • tutorial levels don't get selected (as easy) when we're above this level

• initial tutorial

  • explain level progress (gathering stars from doing challenges)

• the tutorial also needs to explain how the equations are created from the text of the assignment – algebra actually comes later after children do these assignments without thinking of them as variables

• move it to bananas.jacek.cz

• say "back to stats" instead of "back to overview" when coming from stats

• assignment page can show incorrect attempts

• more levels?

  • negative numbers
  • a,b,c... Alex, Bobby, Cass, ... - each run x,y,z,... meters, totaling N seconds; what's the speed of each runner? – e.g. backstory - a relay race game (also practices converting speed, time, and distance)
  • triangle: a + b = 1, b + c = 2, a + c = 3 - draw as triangle

• add other types of maths: ratios? fractions? decimals?

Levels

js/levels/index.js defines the levels

Solution steps:

When the program can check the reasoning, here are some allowed (and recognized) solution steps:

1. (1) ± (2)
2. N*(1) ± M*(2)
3. (1) ± N
4. (1) */ N
5. a in (1)
6. (2) in (1)
7. simplify(1)
8. split(1)
9. reorg(1)
10. flip(1)

Server

The server is a Google Cloud function that stores the assignments for registered users.

To deploy the server, set up your gloud config properly and run npm run deploy.

As of July 2021, users are registered manually by creating an id (in server/ run npm run genid) and then creating a corresponding entity in the datastore by hand.

Data is stored in datastore entities with the entity name matching the user code, and a single un-indexed property json with the stringified DBUserState.

The basic stringified DBUserState is

{
  "info": {
    "name": "PUT SOMETHING HERE",
    "score": 0,
    "lastDone": 0,
    "progressTowardsNextLevel": 0,
    "level": 1
  },
  "assignments": []
}

To run a testing local server, change server-config.json, run npm run localds and in another terminal npm run local.

To add a delay to every API request (to simulate slow network), run DELAY=1000 npm run local with 1000 being the millisecond time for the desired delay.

API:

• get user information: name, progress, score, level, last day of finished assignments (GET)
• save done assignment (no overwrite, POST), returns recomputed user information
• retrieve all done assignments for the stats page (GET)
• check that a user is registered (POST)

/api/users/:code (GET) /api/users/:code/assignments (GET, POST) /api/users/:code/sign-in (POST)

TO-DO

• the server should check that the assignments you're submitting are as would be generated by our code, and if not they don't count towards progress
• add tests for shared-with-server/assignments.ts – especially that recomputeUserProgress and addToUserProgress agree
• add sign-out
• maybe user codes can be created by google-authenticated users (anyone)?
  • maybe a user email address can also be an access code?
• rate limit accesses to 60 per minute? per IP address

Consider threats:

• somebody brute-forces IDs and finds existing users
• people share a code and communicate through solution texts