Add Super Food Feature: Flash, 5s Timeout, Double Score, Dual-Language Comments

README.rst

@@ -129,6 +129,57 @@ Free Python Games also provides an entry-point script for compatibility with
   $ pipx install freegames
   $ freegames play life
 
+----
+
+How to Run Each Game (简化运行方法)
+=====================================
+
+To run any game from the `free-python-games` collection:
+
+1. Make sure Python 3 is installed.
+2. Open your terminal or command prompt.
+3. Use the following command to play a game::
+
+   python3 -m freegames.snake
+
+Replace ``snake`` with other game names like ``pong``, ``memory``, etc.
+
+To view a list of available games::
+
+   python3 -m freegames
+
+----
+
+Quick Start for Chinese Users（中文快速指南）
+=============================================
+
+欢迎使用 free-python-games！
+
+这是一个适合 Python 初学者的小游戏合集，包括贪吃蛇、拼图、乒乓球等经典游戏。
+
+步骤如下：
+
+1. 安装 Python 3（建议官网安装最新版）；
+2. 使用以下命令安装项目::
+
+   pip install freegames
+
+3. 运行游戏，例如::
+
+   python3 -m freegames.snake  # 贪吃蛇
+   python3 -m freegames.pong   # 乒乓球
+
+如无法运行，请尝试：
+- 检查 Python 环境变量；
+- 尝试使用 `python` 代替 `python3`；
+- 确认已正确安装模块。
+
+查看所有游戏列表::
+
+   python3 -m freegames
+
+Enjoy coding and have fun!
+
 
 Free Games
 ----------

src/freegames/snake.py

@@ -10,27 +10,71 @@
 
 from random import randrange
 from turtle import *
-
 from freegames import square, vector
 
-food = vector(0, 0)
+# 蛇身体列表，初始有一节 / Snake body list, starts with one segment
 snake = [vector(10, 0)]
+
+# 移动方向 / Movement direction
 aim = vector(0, -10)
 
+# 普通食物位置 / Regular food position
+food = vector(0, 0)
+
+# 超级食物位置（None 表示不存在）/ Super food position (None = not on map)
+super_food = None
+
+# 超级食物是否可见（用于闪烁）/ Whether the super food is visible (flashing effect)
+super_food_active = False
+
+# 超级食物倒计时（单位：10ms）/ Countdown for super food (in units of 100ms)
+super_food_timer = 0
+
+# 已吃普通食物数量（每5个触发超级食物）/ Normal food count (trigger super food every 5)
+normal_food_count = 0
+
+# 闪烁状态控制 / Flashing toggle
+flash_state = True
+
 
 def change(x, y):
-    """Change snake direction."""
+    """改变蛇的移动方向 / Change snake movement direction"""
     aim.x = x
     aim.y = y
 
 
 def inside(head):
-    """Return True if head inside boundaries."""
+    """判断是否在游戏边界内 / Check if the head is within bounds"""
     return -200 < head.x < 190 and -200 < head.y < 190
 
 
+def place_food_randomly():
+    """生成新的食物位置 / Place food at random position"""
+    return vector(randrange(-15, 15) * 10, randrange(-15, 15) * 10)
+
+
+def draw():
+    """绘制蛇、普通食物、超级食物 / Draw snake, food, and super food"""
+    clear()
+
+    for body in snake:
+        square(body.x, body.y, 9, 'green')
+
+    square(food.x, food.y, 9, 'red')
+
+    # 如果有超级食物并且当前处于激活状态则绘制 / Draw super food if active
+    if super_food and super_food_active:
+        color = 'gold' if flash_state else 'orange'
+        square(super_food.x, super_food.y, 9, color)
+
+    update()
+
+
 def move():
-    """Move snake forward one segment."""
+    """控制蛇移动、吃食物和碰撞检测 / Handle snake movement, food eating and collision"""
+    global food, super_food, normal_food_count
+    global super_food_timer, super_food_active
+
     head = snake[-1].copy()
     head.move(aim)
 
@@ -42,22 +86,45 @@ def move():
     snake.append(head)
 
     if head == food:
-        print('Snake:', len(snake))
-        food.x = randrange(-15, 15) * 10
-        food.y = randrange(-15, 15) * 10
+        print('普通食物 +1 / Normal food +1')
+        food = place_food_randomly()
+        normal_food_count += 1
+
+        # 每吃5个生成一个超级食物 / Spawn super food every 5 normal foods
+        if normal_food_count % 5 == 0:
+            super_food = place_food_randomly()
+            super_food_active = True
+            super_food_timer = 50  # 5秒 = 50 * 100ms
+    elif super_food and head == super_food:
+        print('超级食物 +2！/ Super food +2!')
+        snake.append(snake[-1].copy())  # 额外加一节 / One extra segment
+        super_food = None
+        super_food_active = False
     else:
-        snake.pop(0)
+        snake.pop()
 
-    clear()
+    draw()
+    ontimer(move, 100)
 
-    for body in snake:
-        square(body.x, body.y, 9, 'black')
 
-    square(food.x, food.y, 9, 'green')
-    update()
-    ontimer(move, 100)
+def tick_super_food():
+    """定时器函数：控制超级食物闪烁和超时消失 / Super food flash and timeout control"""
+    global flash_state, super_food_timer, super_food, super_food_active
+
+    if super_food_active:
+        flash_state = not flash_state  # 颜色闪烁 / Toggle color
 
+        super_food_timer -= 1
+        if super_food_timer <= 0:
+            print('超级食物消失 / Super food expired')
+            super_food = None
+            super_food_active = False
 
+    draw()
+    ontimer(tick_super_food, 100)
+
+
+# 初始化窗口和控制 / Game window and controls
 setup(420, 420, 370, 0)
 hideturtle()
 tracer(False)
@@ -66,5 +133,8 @@ def move():
 onkey(lambda: change(-10, 0), 'Left')
 onkey(lambda: change(0, 10), 'Up')
 onkey(lambda: change(0, -10), 'Down')
+
+# 启动主循环 / Start main game loop
 move()
-done()
+tick_super_food()
+done()