arcadeturtle 0.1.0__tar.gz

arcadeturtle-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+.venv/
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+tests/manual/_out_*.png

arcadeturtle-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zack-riftwalker
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

arcadeturtle-0.1.0/PHASE10_PLAN.md

@@ -0,0 +1,150 @@
+# فاز ۱۰ (گسترش‌یافته) — سازگاری کامل با turtle استاندارد
+
+هدف: **هر اسکریپت turtle واقعی روی اینترنت، فقط با تغییر خط import، روی ArcadeTurtle اجرا شود** — نه فقط بازی مار، بلکه Space Invaders، Pong، Etch-a-Sketch، نقاشی‌های compound-shape و اسکریپت‌های کلاس درس.
+
+مبنای این پلن حدس نیست: خروجی مقایسه‌ی مستقیم `dir()` بین `turtle` استاندارد و `arcadeturtle` است:
+
+| سطح | stdlib | ما داریم | جا مانده |
+|---|---|---|---|
+| توابع سطح ماژول | ۱۲۲ | ۷۳ | **۴۹** |
+| متدهای Turtle | ۸۴ | ۵۶ | **۲۸** |
+| متدهای Screen | — | — | **۷** |
+
+موارد جامانده در ۸ زیرفاز دسته‌بندی شده‌اند، به ترتیب «بیشترین استفاده در آموزش‌های واقعی، اول».
+
+---
+
+## ۱۰.۱ — بردهای آسان: توابع سطح ماژول که فقط باید وصل شوند
+
+این‌ها از قبل روی `Screen()` یا `Turtle` ما وجود دارند ولی در سطح ماژول (سبک `import arcadeturtle as turtle; turtle.setup(...)`) در دسترس نیستند. فقط forwarding لازم است:
+
+```
+setup, window_width, window_height, screensize, bye, exitonclick,
+clearscreen, resetscreen, bgpic*, addshape*, register_shape*,
+setworldcoordinates*, mode*, delay*, turtles*
+```
+(ستاره‌دارها فعلاً خطای «پشتیبانی نمی‌شود» می‌دهند — همان خطا را در سطح ماژول هم بدهند تا بعداً که پیاده شدند خودکار وصل باشند.)
+
+همچنین aliasهای کلاس برای اسکریپت‌هایی که مستقیم استفاده می‌کنند:
+- `Pen = Turtle` و `RawTurtle = Turtle` و `RawPen = Turtle` (در stdlib هم `Pen` همان `Turtle` است)
+- `TurtleScreen`/`ScrolledCanvas`/`getcanvas` → خطای مهربان «مخصوص Tkinter است» (این‌ها فقط در اسکریپت‌های embedding استفاده می‌شوند)
+- استثنای `Terminator` (وقتی پنجره بسته می‌شود ولی اسکریپت هنوز دستور می‌دهد — الان چه می‌کنیم؟ باید همین استثنا را بدهیم)
+
+**سختی: کم. اثر: فوری — ده‌ها اسکریپت فقط به‌خاطر همین‌ها می‌شکنند.**
+
+## ۱۰.۲ — Vec2D و کوئری‌های برداری
+
+در stdlib، `position()`/`pos()` یک **`Vec2D`** برمی‌گرداند نه تاپل ساده — و آموزش‌های فیزیک/بازی رویش جمع و ضرب برداری می‌کنند: `t.goto(t.pos() + Vec2D(0, 10))`. الان تاپل برمی‌گردانیم و آن اسکریپت‌ها می‌ترکند.
+
+- کلاس `Vec2D(tuple)` با `+`, `-`, `*` (اسکالر و داخلی)، `abs`, `rotate` — پیاده‌سازی stdlib کوچک است و می‌شود همان را الگو گرفت
+- `position()`, `pos()`, `towards`/`distance` ورودی Vec2D بپذیرند
+- `teleport(x, y, fill_gap=False)` (اضافه‌شده در پایتون ۳.۱۲): مثل goto ولی بدون خط و بدون انیمیشن، حتی با قلم پایین
+
+**سختی: کم.**
+
+## ۱۰.۳ — شکل‌ها: بزرگ‌ترین شکاف واقعی
+
+پرتکرارترین دلیل شکستن آموزش‌های بازی (Space Invaders، مسابقه ماشین، …):
+
+- **`register_shape(name, polygon)`** — شکل چندضلعی سفارشی
+- **`Shape` class + compound shapes** — `Shape("compound")` با `addcomponent(poly, fill, outline)`؛ در نقاشی‌های پیشرفته رایج است
+- **`register_shape("image.gif")`** — شکل تصویری. Arcade خودش Sprite/Texture دارد؛ باید GIF *و* PNG را پشتیبانی کنیم (PNG مزیت ماست، GIF برای سازگاری)
+- `getshapes()` — فهرست شکل‌های ثبت‌شده
+- `get_shapepoly()` — چندضلعی شکل فعلی
+- **`resizemode("auto"|"user"|"noresize")`** — در stdlib با `pensize` یا `shapesize` شکل بزرگ می‌شود؛ خیلی از بازی‌ها `shapesize` با `resizemode` می‌زنند
+- `tilt(angle)`, `tiltangle()`, `settiltangle()` — چرخش ظاهر بدون تغییر جهت حرکت (در انیمیشن چرخ ماشین و سفینه استفاده می‌شود)
+- `shearfactor()`, `shapetransform()` — کم‌استفاده ولی برای «کامل بودن» لازم؛ ماتریس ۲×۲ روی چندضلعی کرسر
+
+نکته معماری: `_renderer.py` الان کرسر را از `SHAPE_POLYGONS` ثابت می‌کشد. باید یک **رجیستری شکل per-engine** جایگزین شود که سه نوع دارد: polygon، compound، image. مسیر رسم image از مسیر polygon جداست (arcade.Texture + draw)؛ تصویر باید با `tracer(0)` هم درست کار کند.
+
+**سختی: متوسط تا زیاد. اثر: بالاترین — این زیرفاز بیشترین اسکریپت‌ها را زنده می‌کند.**
+
+## ۱۰.۴ — undo
+
+در آموزش کودکان و محیط‌های تعاملی زیاد استفاده می‌شود:
+
+- هر عمل قابل‌بازگشت (حرکت، چرخش، رنگ، write، stamp، fill) یک entry در **بافر undo مخصوص همان لاک‌پشت** بگذارد
+- `undo()` آخرین entry را برگرداند: state منطقی + حذف از renderer (خط/متن/مهر با شناسه‌ی خودش پاک شود — زیرساخت `turtle_id` که در فاز رفع باگ‌ها ساختیم دقیقاً همین‌جا به کار می‌آید)
+- `setundobuffer(size)` و `undobufferentries()`؛ پیش‌فرض stdlib بافر ۱۰۰۰تایی است؛ `None` یعنی خاموش
+- تعامل با انیمیشن: undo روی فرمانی که هنوز در صف است باید آن را از صف بردارد، نه اینکه اجرا و بعد برعکس کند
+
+**سختی: متوسط. ریسک: تعامل صف/undo — تست دقیق لازم دارد.**
+
+## ۱۰.۵ — رویدادهای باقی‌مانده
+
+- **`Turtle.onclick(fn)`** — کلیک *روی خود لاک‌پشت* (نه صفحه). الان فقط کلیک صفحه داریم. لازمه‌اش hit-test روی چندضلعی/تصویر کرسر است
+- **`Turtle.ondrag(fn)`** — کشیدن لاک‌پشت با موس؛ پایه‌ی آموزش محبوب «Etch-A-Sketch» و اسباب‌بازی‌های تعاملی. نیازمند `on_mouse_drag` در `_window.py`
+- `Turtle.onrelease(fn)` — رهاکردن موس روی لاک‌پشت
+- `Screen.delay(ms)` — تأخیر بین به‌روزرسانی‌ها؛ باید روی سرعت پخش صف اثر بگذارد (نگاشت به مدل انیمیشن ما: یک ضریب سراسری)
+- معنای دقیق `tracer(n)` برای n>1: هر n اقدام یک به‌روزرسانی — الان فقط 0 و 1 را درست انجام می‌دهیم
+
+**سختی: متوسط.**
+
+## ۱۰.۶ — چندضلعی‌سازی و clone
+
+- `begin_poly()`, `end_poly()`, `get_poly()` — ضبط مسیر حرکت به‌عنوان چندضلعی؛ همراه `register_shape` برای ساخت شکل سفارشی «با خود لاک‌پشت» استفاده می‌شود
+- **`clone()`** — کپی کامل لاک‌پشت (state + شکل + قلم)؛ در بعضی نسخه‌های بازی مار برای بدنه استفاده می‌شود
+- `getturtle()`/`getpen()` — خودِ شیء را برمی‌گرداند (یک خط)
+- `pen()` — گرفتن/ست‌کردن دسته‌ای همه ویژگی‌های قلم به‌صورت dict؛ اسکریپت‌های پیشرفته برای ذخیره/بازیابی وضعیت استفاده می‌کنند
+- `degrees(fullcircle)`, `radians()` — تغییر واحد زاویه؛ روی همه ورودی/خروجی‌های زاویه اثر می‌گذارد (`left/right/heading/setheading/towards`)
+
+**سختی: کم تا متوسط. `degrees/radians` باید مرکزی در `TurtleState` حل شود نه پراکنده.**
+
+## ۱۰.۷ — دیالوگ‌های ورودی و پس‌زمینه تصویری
+
+- **`textinput(title, prompt)`** و **`numinput(title, prompt, default, minval, maxval)`** — چون Arcade دیالوگ آماده ندارد، ساده‌ترین راهِ سازگار: `tkinter.simpledialog` (در همه نصب‌های استاندارد پایتون هست و لازم نیست پنجره turtle مال Tk باشد). نسخه فارسی‌پسند: عنوان/پیام فارسی درست رندر شود
+- **`bgpic("image.png"|"nopic")`** — تصویر پس‌زمینه، وسط‌چین مثل stdlib؛ GIF و PNG
+- `Screen.mode("standard"|"logo"|"world")` — حالت logo (زاویه صفر = شمال، ساعتگرد) در آموزش‌های مدرسه‌ای مکرر است؛ باید در `_coords.py`/`TurtleState` به‌صورت متمرکز اعمال شود
+- **`setworldcoordinates(llx, lly, urx, ury)`** — مختصات دلخواه کاربر؛ چون تبدیل مختصات ما متمرکز در `_coords.py` است، این فقط یک لایه‌ی scale/offset روی همان است — معماری فعلی دقیقاً برای همین ساخته شد
+
+**سختی: متوسط. `mode('logo')` و world باید با هم طراحی شوند چون هر دو تبدیل مختصات/زاویه‌اند.**
+
+## ۱۰.۸ — تمیزکاری نهایی سازگاری
+
+- `Screen.turtles()` و `turtles()` سطح ماژول — فهرست لاک‌پشت‌ها (WeakSet فاز قبل را داریم)
+- بازبینی امضای همه توابع موجود در برابر stdlib (آرگومان‌های اختیاری، مقادیر برگشتی — مثلاً `pencolor()` بدون آرگومان در stdlib رشته یا تاپل برمی‌گرداند بسته به نحوه‌ی ست‌شدن؛ ما همین کار را می‌کنیم؟ تست شود)
+- `write_docstringdict` → no-op بی‌صدا (فقط برای ترجمه docstring در stdlib است)
+- هر چیزی که آگاهانه پیاده نمی‌شود (getcanvas، ScrolledCanvas) خطای مهربانِ «چرا» بدهد
+- **به‌روزرسانی کامل جدول سازگاری README** — بعد از این فاز، ستون ❌ باید تقریباً خالی باشد
+
+---
+
+## آزمون‌های طلایی جدید (معیار پایان فاز ۱۰)
+
+مثل «آزمون طلایی مار»، این ۶ اسکریپت از آموزش‌های واقعی و محبوب اینترنت، فقط با تغییر import باید اجرا شوند:
+
+1. **Space Invaders** (سبک Real Python) — `register_shape` تصویری، چند لاک‌پشت، کیبورد، برخورد
+2. **Pong** — دو راکت، توپ، `ontimer`/حلقه، امتیاز
+3. **Etch-A-Sketch** — `ondrag` و `onclick` روی لاک‌پشت
+4. **نقاشی compound-shape** — `Shape("compound")` + `addcomponent`
+5. **اسکریپت undo تعاملی** — نقاشی با کیبورد + دکمه undo
+6. **اسکریپت مختصات جهانی** — `setworldcoordinates` + رسم نمودار ساده
+
+هرکدام: یک اسکریپت راننده‌ی خودکار در `tests/manual/` + تست دود compile در `tests/test_examples_smoke.py`.
+
+## ترتیب اجرا و منطق
+
+```
+۱۰.۱ (وصل‌کردن‌ها — یک روز، اثر فوری)
+→ ۱۰.۲ (Vec2D — پایه‌ی بقیه چون position همه‌جا استفاده می‌شود)
+→ ۱۰.۳ (شکل‌ها — بزرگ‌ترین برد)
+→ ۱۰.۵ (رویدادها — بعدش Etch-A-Sketch و Space Invaders تست می‌شوند)
+→ ۱۰.۴ (undo — مستقل، ولی بعد از شکل‌ها تا undo مهر/تصویر هم پوشش بگیرد)
+→ ۱۰.۶ (poly/clone/degrees)
+→ ۱۰.۷ (دیالوگ‌ها، bgpic، world/logo)
+→ ۱۰.۸ (تمیزکاری + README + آزمون‌های طلایی نهایی)
+```
+
+هر زیرفاز: پیاده‌سازی → تست‌های headless → تأیید دستی با پنجره → کامیت جدا.
+
+## ریسک‌های اصلی
+
+| ریسک | مقابله |
+|---|---|
+| تصاویر (shape/bgpic) با معماری «بافر پخته» ما تداخل کنند | تصویر جدا از ShapeElementList رندر می‌شود؛ از همان الگوی متن (arcade.Text) پیروی کند |
+| undo × صف انیمیشن حالت‌های لبه‌ای بسازد | undo اول صف را خالی می‌کند (مثل tracer(0)) بعد برمی‌گرداند — ساده و قابل پیش‌بینی |
+| mode('logo') همه محاسبات زاویه را بشکند | تبدیل زاویه فقط در TurtleState/_coords متمرکز بماند؛ تست مقایسه‌ای مستقیم با stdlib برای هر ۴ حالت |
+| tkinter برای دیالوگ‌ها در بعضی محیط‌ها نباشد | try/except با خطای مهربان + مستندسازی |
+| حجم زیاد → فرسایش | هر زیرفاز خروجی مستقل قابل تست دارد؛ بعد از ۱۰.۳ هر لحظه می‌شود متوقف شد و منتشر کرد |
+
+بعد از پایان فاز ۱۰ → فاز ۹ (CI، PyPI، انتشار) طبق تصمیم قبلی.

arcadeturtle-0.1.0/PKG-INFO

@@ -0,0 +1,192 @@
+Metadata-Version: 2.4
+Name: arcadeturtle
+Version: 0.1.0
+Summary: کتابخانه آموزشی لاک‌پشت با موتور Arcade — همان API ماژول turtle، با گرافیک مدرن و پشتیبانی فارسی
+Project-URL: Homepage, https://github.com/zack-riftwalker/arcadeturtle
+Project-URL: Repository, https://github.com/zack-riftwalker/arcadeturtle
+Project-URL: Issues, https://github.com/zack-riftwalker/arcadeturtle/issues
+Author: zack-riftwalker
+License-Expression: MIT
+License-File: LICENSE
+Keywords: arcade,education,farsi,graphics,persian,turtle
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Education
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Education
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: arabic-reshaper>=3.0
+Requires-Dist: arcade<4,>=3.0
+Requires-Dist: python-bidi>=0.4
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ArcadeTurtle 🐢
+
+کتابخانه‌ای آموزشی: همان دستورهای ماژول استاندارد `turtle` پایتون، اما با
+موتور گرافیکی مدرن **[Arcade](https://api.arcade.academy/)** — حرکت نرم،
+پنجره باکیفیت، و پشتیبانی کامل از متن فارسی در `write()`.
+
+![نمونه خروجی ArcadeTurtle](docs/screenshot.png)
+
+## نصب
+
+```bash
+python -m venv .venv
+.venv\Scripts\activate        # ویندوز
+pip install -e .
+```
+
+## شروع سریع
+
+```python
+import arcadeturtle as turtle
+
+for _ in range(4):
+    turtle.forward(100)
+    turtle.left(90)
+
+turtle.done()
+```
+
+همین! هر برنامه‌ای که با ماژول `turtle` استاندارد نوشته باشی، معمولاً فقط با
+تغییر همین یک خط `import` روی ArcadeTurtle هم اجرا می‌شود.
+
+پوشش API در سطح ماژول ۱۰۰٪ است (هر نام در `turtle.__all__` استاندارد این‌جا
+هم وجود دارد). برای اثبات این ادعا، هفت «آزمون طلایی» در پوشه‌ی
+[`examples/`](examples/) هستند: اسکریپت‌هایی به سبک رایج آموزش‌های اینترنتی
+(بازی مار، پونگ، فضاپیمای مهاجم، Etch-A-Sketch، شکل ترکیبی، نقاشی با undo،
+نمودار با مختصات جهانی) که فقط با تغییر `import` روی ArcadeTurtle اجرا
+می‌شوند.
+
+## مثال‌ها
+
+مثال‌ها در پوشه‌ی [`examples/`](examples/) از ساده به پیشرفته مرتب‌اند:
+
+| فایل | چه چیزی یاد می‌دهد |
+|---|---|
+| [`00_healthcheck.py`](examples/00_healthcheck.py) | آیا Arcade و متن فارسی روی سیستم تو کار می‌کنند؟ |
+| [`01_square.py`](examples/01_square.py) | اولین حرکت، چرخش و حلقه |
+| [`02_star.py`](examples/02_star.py) | ستاره پنج‌پر، رنگ پس‌زمینه |
+| [`03_polygon_function.py`](examples/03_polygon_function.py) | نوشتن تابع با پارامتر |
+| [`04_color_spiral.py`](examples/04_color_spiral.py) | حلقه‌های تودرتو، `speed(0)` |
+| [`05_filled_shapes.py`](examples/05_filled_shapes.py) | `begin_fill`/`end_fill`، `dot`، نوشتن فارسی |
+| [`06_keyboard_drive.py`](examples/06_keyboard_drive.py) | کنترل با کیبورد (`onkeypress`) |
+| [`07_click_paint.py`](examples/07_click_paint.py) | رویداد کلیک موس (`onscreenclick`) |
+| [`08_snake_game.py`](examples/08_snake_game.py) | بازی کامل مار، چند لاک‌پشت، تابلوی امتیاز فارسی |
+| [`golden_snake_original.py`](examples/golden_snake_original.py) | یک اسکریپت مار به سبک رایج اینترنتی — فقط با تغییر `import` اجرا می‌شود |
+| [`09_compound_shape_art.py`](examples/09_compound_shape_art.py) | `Shape("compound")`، `addcomponent`، `stamp` |
+| [`10_etch_a_sketch.py`](examples/10_etch_a_sketch.py) | `Turtle.ondrag` — کشیدن با موس |
+| [`11_undo_drawing.py`](examples/11_undo_drawing.py) | نقاشی با کیبورد + `undo()` |
+| [`12_world_coordinates_chart.py`](examples/12_world_coordinates_chart.py) | `setworldcoordinates` — رسم نمودار در واحدهای داده |
+| [`13_pong.py`](examples/13_pong.py) | بازی دونفره، `ontimer`، برخورد |
+| [`14_space_invaders.py`](examples/14_space_invaders.py) | `register_shape` با فایل تصویری، برخورد گلوله/دشمن |
+
+## جدول سازگاری با ماژول `turtle` استاندارد
+
+### ✅ کامل پشتیبانی می‌شود
+
+حرکت: `forward`/`fd`، `backward`/`bk`/`back`، `left`/`lt`، `right`/`rt`،
+`goto`/`setpos`/`setposition`، `setx`، `sety`، `home`، `setheading`/`seth` •
+قلم: `penup`/`pu`/`up`، `pendown`/`pd`/`down`، `isdown`، `pensize`/`width`،
+`pencolor`، `speed` • ترسیم: `circle`، `dot`، `stamp`، `clearstamp`،
+`clearstamps`، `begin_fill`، `end_fill`، `filling`، `fillcolor`، `color`،
+`write` (با پشتیبانی فارسی خودکار) • ظاهر: `shape`، `shapesize`/`turtlesize`،
+`resizemode`، `tilt`، `tiltangle`، `settiltangle`، `shearfactor`،
+`shapetransform`، `get_shapepoly`، `hideturtle`/`ht`، `showturtle`/`st`،
+`isvisible` • شکل‌های سفارشی: `register_shape`/`addshape` (چندضلعی، شکل
+ترکیبی compound، یا فایل تصویری PNG/GIF)، `Shape` class با `addcomponent`،
+`getshapes` • کوئری: `position`/`pos` (به‌صورت `Vec2D`)، `xcor`، `ycor`،
+`heading`، `towards`، `distance`، `teleport`، `degrees`، `radians` (واحد
+اندازه‌گیری زاویه، جداگانه برای هر لاک‌پشت) • رویداد: `listen`، `onkey`،
+`onkeypress`، `onkeyrelease`، `onclick`/`onscreenclick`، `ontimer`، `tracer`،
+`update`، `Turtle.onclick`/`ondrag`/`onrelease` (کلیک/کشیدن روی خودِ
+لاک‌پشت) • برگشت: `undo`، `setundobuffer`، `undobufferentries` (بافر
+جداگانه برای هر لاک‌پشت) • ابزار: `pen` (گرفتن/ست‌کردن دسته‌ای وضعیت قلم)،
+`getturtle`/`getpen`، `clone`، `begin_poly`/`end_poly`/`get_poly` (ضبط
+چندضلعی دلخواه برای `register_shape` بعدی) • صفحه: `bgcolor`، `title`،
+`colormode`، `mode` (`standard`/`logo`/`world`)، `setworldcoordinates`،
+`bgpic`، `textinput`، `numinput`، `clear`، `reset`، `done`/`mainloop` •
+کلاس‌ها: `Turtle()`/`Pen()`/`RawTurtle()`/`RawPen()` (چند نمونه مستقل)،
+`Screen()` (سینگلتون) با `setup`، `window_width`/`window_height`،
+`exitonclick`، `bye`، `Vec2D`.
+
+`clear`/`reset` دقیقاً مثل turtle اصلی تفکیک شده‌اند: `Turtle.clear()` فقط
+نقاشی‌های همان لاک‌پشت را پاک می‌کند، `Screen.clear()` همه‌چیز را، و
+`Screen.reset()` علاوه بر آن همه لاک‌پشت‌ها را به حالت اولیه برمی‌گرداند.
+
+### 🟡 رفتار کمی متفاوت
+
+- **`speed`**: عدد بین ۰ تا ۱۰ (یا نام‌های `fastest`/`fast`/`normal`/`slow`/
+  `slowest`)؛ سرعت واقعی پیکسل بر ثانیه با turtle اصلی یکی نیست، ولی معنای
+  نسبی (بزرگ‌تر = سریع‌تر، ۰ = آنی) همان است.
+- **`colormode`**: مثل turtle اصلی کار می‌کند (پیش‌فرض ۲۵۵؛ برای رنگ‌های
+  اعشاری اول `colormode(1.0)` را صدا بزن) — ولی برخلاف turtle اصلی، حالت رنگ
+  سراسری است و به یک شیء Screen خاص گره نخورده.
+- **شکل تصویری می‌چرخد** — برخلاف turtle اصلی که صراحتاً می‌گوید «شکل‌های
+  تصویری با چرخیدن لاک‌پشت نمی‌چرخند»، این‌جا عمداً برعکس تصمیم گرفته شده:
+  تصویر با heading می‌چرخد، چون هدف پشتیبانی از بازی‌های سبک Space Invaders/
+  مسابقه‌ای است که انتظار چرخش دارند. اگر تصویرت را با «رو به شرق» طراحی کنی
+  (نوکش رو به راست)، در heading=0 دقیقاً هم‌جهت با شکل‌های چندضلعی می‌ایستد.
+- **`shearfactor`/`shapetransform`**: ساده‌سازی‌شده نسبت به فرمول داخلی
+  turtle اصلی؛ نتیجه‌ی بصری مشابه است ولی از نظر عددی («تجزیه»ی دقیق ماتریس)
+  یکی نیست. برای اکثر اسکریپت‌های آموزشی که این‌ها را جداگانه صدا می‌زنند
+  فرقی احساس نمی‌شود.
+- **`resizemode("auto")`**: اندازه‌ی شکل برابر `pensize/5` محاسبه می‌شود —
+  یک تقریب مستند، نه فرمول دقیق stdlib.
+- **`Turtle.onclick`/`ondrag`/`onrelease`**: تشخیص «روی لاک‌پشت» با یک دایره‌ی
+  احاطه‌کننده است، نه برخورد دقیق نقطه-در-چندضلعی — برای تعامل معمولی
+  (مثل کشیدن با موس) کافی است.
+- **`undo`**: بافر جداگانه برای هر لاک‌پشت (نه یک بافر مشترک سراسری)،
+  و به‌جای بازسازی دقیق مثل stdlib، هر رکورد آنی state قبلی را برمی‌گرداند.
+  همان دستورهایی که stdlib هم undo می‌کند پوشش داده شده: حرکت، چرخش، مهر،
+  نوشته، `dot`، `begin_fill`/`end_fill`، و ویژگی‌های قلم. تغییرات ظاهری مثل
+  `shape`/`tilt`/`resizemode` در stdlib هم قابل undo نیستند.
+- **`bgpic`**: تصویر پس‌زمینه با اندازه‌ی طبیعی خودش وسط‌چین می‌شود (مثل
+  stdlib) — کش داده نمی‌شود که کل پنجره را پر کند.
+- **`textinput`/`numinput`**: با `tkinter.simpledialog` پیاده شده‌اند (چون
+  Arcade دیالوگ ورودی آماده ندارد)؛ یک پنجره‌ی جدا از پنجره‌ی اصلی باز
+  می‌شود. اگر tkinter روی سیستم در دسترس نباشد، خطای مهربان می‌دهند.
+
+### ❌ هنوز پشتیبانی نمی‌شود
+
+`getscreen()` چندپنجره‌ای (فقط یک پنجره در هر زمان)، و `write(move=True)`.
+
+این‌ها به‌صراحت خطای فارسی مهربان می‌دهند، نه رفتار خاموش یا نادرست.
+
+دلیل `write(move=True)`: برای جابه‌جا کردن قلم به انتهای متن باید عرض متن
+اندازه‌گیری شود که به پنجره‌ی باز نیاز دارد، ولی `write()` معمولاً قبل از
+`done()` صدا زده می‌شود. به‌جایش خودت قلم را جابه‌جا کن:
+
+```python
+penup()
+write("سلام")
+goto(xcor() + 60, ycor())
+pendown()
+```
+
+## پشت صحنه چطور کار می‌کند؟
+
+سه تصمیم معماری کلیدی (شرح کامل در [ROADMAP.md](ROADMAP.md)):
+
+1. **صف فرمان واحد**: هر فراخوانی دستور یک «فرمان» به یک صف FIFO مشترک
+   اضافه می‌کند. وضعیت منطقی لاک‌پشت (برای `position()` و مانند آن) بلافاصله
+   به‌روز می‌شود؛ پخش انیمیشنِ آن روی صفحه در فریم‌های بعدی انجام می‌شود.
+2. **تبدیل مختصات متمرکز**: تنها در `_coords.py` — مبدأ Turtle وسط صفحه،
+   مبدأ Arcade گوشه پایین-چپ.
+3. **بافر خط پخته‌شده**: خط‌های تمام‌شده یک‌بار در `ShapeElementList` Arcade
+   ساخته می‌شوند تا نقاشی‌های پیچیده (مثل مارپیچ) کند نشوند.
+
+## اجرای تست‌ها
+
+```bash
+pip install -e ".[dev]"
+pytest
+```

arcadeturtle-0.1.0/README.md

@@ -0,0 +1,162 @@
+# ArcadeTurtle 🐢
+
+کتابخانه‌ای آموزشی: همان دستورهای ماژول استاندارد `turtle` پایتون، اما با
+موتور گرافیکی مدرن **[Arcade](https://api.arcade.academy/)** — حرکت نرم،
+پنجره باکیفیت، و پشتیبانی کامل از متن فارسی در `write()`.
+
+![نمونه خروجی ArcadeTurtle](docs/screenshot.png)
+
+## نصب
+
+```bash
+python -m venv .venv
+.venv\Scripts\activate        # ویندوز
+pip install -e .
+```
+
+## شروع سریع
+
+```python
+import arcadeturtle as turtle
+
+for _ in range(4):
+    turtle.forward(100)
+    turtle.left(90)
+
+turtle.done()
+```
+
+همین! هر برنامه‌ای که با ماژول `turtle` استاندارد نوشته باشی، معمولاً فقط با
+تغییر همین یک خط `import` روی ArcadeTurtle هم اجرا می‌شود.
+
+پوشش API در سطح ماژول ۱۰۰٪ است (هر نام در `turtle.__all__` استاندارد این‌جا
+هم وجود دارد). برای اثبات این ادعا، هفت «آزمون طلایی» در پوشه‌ی
+[`examples/`](examples/) هستند: اسکریپت‌هایی به سبک رایج آموزش‌های اینترنتی
+(بازی مار، پونگ، فضاپیمای مهاجم، Etch-A-Sketch، شکل ترکیبی، نقاشی با undo،
+نمودار با مختصات جهانی) که فقط با تغییر `import` روی ArcadeTurtle اجرا
+می‌شوند.
+
+## مثال‌ها
+
+مثال‌ها در پوشه‌ی [`examples/`](examples/) از ساده به پیشرفته مرتب‌اند:
+
+| فایل | چه چیزی یاد می‌دهد |
+|---|---|
+| [`00_healthcheck.py`](examples/00_healthcheck.py) | آیا Arcade و متن فارسی روی سیستم تو کار می‌کنند؟ |
+| [`01_square.py`](examples/01_square.py) | اولین حرکت، چرخش و حلقه |
+| [`02_star.py`](examples/02_star.py) | ستاره پنج‌پر، رنگ پس‌زمینه |
+| [`03_polygon_function.py`](examples/03_polygon_function.py) | نوشتن تابع با پارامتر |
+| [`04_color_spiral.py`](examples/04_color_spiral.py) | حلقه‌های تودرتو، `speed(0)` |
+| [`05_filled_shapes.py`](examples/05_filled_shapes.py) | `begin_fill`/`end_fill`، `dot`، نوشتن فارسی |
+| [`06_keyboard_drive.py`](examples/06_keyboard_drive.py) | کنترل با کیبورد (`onkeypress`) |
+| [`07_click_paint.py`](examples/07_click_paint.py) | رویداد کلیک موس (`onscreenclick`) |
+| [`08_snake_game.py`](examples/08_snake_game.py) | بازی کامل مار، چند لاک‌پشت، تابلوی امتیاز فارسی |
+| [`golden_snake_original.py`](examples/golden_snake_original.py) | یک اسکریپت مار به سبک رایج اینترنتی — فقط با تغییر `import` اجرا می‌شود |
+| [`09_compound_shape_art.py`](examples/09_compound_shape_art.py) | `Shape("compound")`، `addcomponent`، `stamp` |
+| [`10_etch_a_sketch.py`](examples/10_etch_a_sketch.py) | `Turtle.ondrag` — کشیدن با موس |
+| [`11_undo_drawing.py`](examples/11_undo_drawing.py) | نقاشی با کیبورد + `undo()` |
+| [`12_world_coordinates_chart.py`](examples/12_world_coordinates_chart.py) | `setworldcoordinates` — رسم نمودار در واحدهای داده |
+| [`13_pong.py`](examples/13_pong.py) | بازی دونفره، `ontimer`، برخورد |
+| [`14_space_invaders.py`](examples/14_space_invaders.py) | `register_shape` با فایل تصویری، برخورد گلوله/دشمن |
+
+## جدول سازگاری با ماژول `turtle` استاندارد
+
+### ✅ کامل پشتیبانی می‌شود
+
+حرکت: `forward`/`fd`، `backward`/`bk`/`back`، `left`/`lt`، `right`/`rt`،
+`goto`/`setpos`/`setposition`، `setx`، `sety`، `home`، `setheading`/`seth` •
+قلم: `penup`/`pu`/`up`، `pendown`/`pd`/`down`، `isdown`، `pensize`/`width`،
+`pencolor`، `speed` • ترسیم: `circle`، `dot`، `stamp`، `clearstamp`،
+`clearstamps`، `begin_fill`، `end_fill`، `filling`، `fillcolor`، `color`،
+`write` (با پشتیبانی فارسی خودکار) • ظاهر: `shape`، `shapesize`/`turtlesize`،
+`resizemode`، `tilt`، `tiltangle`، `settiltangle`، `shearfactor`،
+`shapetransform`، `get_shapepoly`، `hideturtle`/`ht`، `showturtle`/`st`،
+`isvisible` • شکل‌های سفارشی: `register_shape`/`addshape` (چندضلعی، شکل
+ترکیبی compound، یا فایل تصویری PNG/GIF)، `Shape` class با `addcomponent`،
+`getshapes` • کوئری: `position`/`pos` (به‌صورت `Vec2D`)، `xcor`، `ycor`،
+`heading`، `towards`، `distance`، `teleport`، `degrees`، `radians` (واحد
+اندازه‌گیری زاویه، جداگانه برای هر لاک‌پشت) • رویداد: `listen`، `onkey`،
+`onkeypress`، `onkeyrelease`، `onclick`/`onscreenclick`، `ontimer`، `tracer`،
+`update`، `Turtle.onclick`/`ondrag`/`onrelease` (کلیک/کشیدن روی خودِ
+لاک‌پشت) • برگشت: `undo`، `setundobuffer`، `undobufferentries` (بافر
+جداگانه برای هر لاک‌پشت) • ابزار: `pen` (گرفتن/ست‌کردن دسته‌ای وضعیت قلم)،
+`getturtle`/`getpen`، `clone`، `begin_poly`/`end_poly`/`get_poly` (ضبط
+چندضلعی دلخواه برای `register_shape` بعدی) • صفحه: `bgcolor`، `title`،
+`colormode`، `mode` (`standard`/`logo`/`world`)، `setworldcoordinates`،
+`bgpic`، `textinput`، `numinput`، `clear`، `reset`، `done`/`mainloop` •
+کلاس‌ها: `Turtle()`/`Pen()`/`RawTurtle()`/`RawPen()` (چند نمونه مستقل)،
+`Screen()` (سینگلتون) با `setup`، `window_width`/`window_height`،
+`exitonclick`، `bye`، `Vec2D`.
+
+`clear`/`reset` دقیقاً مثل turtle اصلی تفکیک شده‌اند: `Turtle.clear()` فقط
+نقاشی‌های همان لاک‌پشت را پاک می‌کند، `Screen.clear()` همه‌چیز را، و
+`Screen.reset()` علاوه بر آن همه لاک‌پشت‌ها را به حالت اولیه برمی‌گرداند.
+
+### 🟡 رفتار کمی متفاوت
+
+- **`speed`**: عدد بین ۰ تا ۱۰ (یا نام‌های `fastest`/`fast`/`normal`/`slow`/
+  `slowest`)؛ سرعت واقعی پیکسل بر ثانیه با turtle اصلی یکی نیست، ولی معنای
+  نسبی (بزرگ‌تر = سریع‌تر، ۰ = آنی) همان است.
+- **`colormode`**: مثل turtle اصلی کار می‌کند (پیش‌فرض ۲۵۵؛ برای رنگ‌های
+  اعشاری اول `colormode(1.0)` را صدا بزن) — ولی برخلاف turtle اصلی، حالت رنگ
+  سراسری است و به یک شیء Screen خاص گره نخورده.
+- **شکل تصویری می‌چرخد** — برخلاف turtle اصلی که صراحتاً می‌گوید «شکل‌های
+  تصویری با چرخیدن لاک‌پشت نمی‌چرخند»، این‌جا عمداً برعکس تصمیم گرفته شده:
+  تصویر با heading می‌چرخد، چون هدف پشتیبانی از بازی‌های سبک Space Invaders/
+  مسابقه‌ای است که انتظار چرخش دارند. اگر تصویرت را با «رو به شرق» طراحی کنی
+  (نوکش رو به راست)، در heading=0 دقیقاً هم‌جهت با شکل‌های چندضلعی می‌ایستد.
+- **`shearfactor`/`shapetransform`**: ساده‌سازی‌شده نسبت به فرمول داخلی
+  turtle اصلی؛ نتیجه‌ی بصری مشابه است ولی از نظر عددی («تجزیه»ی دقیق ماتریس)
+  یکی نیست. برای اکثر اسکریپت‌های آموزشی که این‌ها را جداگانه صدا می‌زنند
+  فرقی احساس نمی‌شود.
+- **`resizemode("auto")`**: اندازه‌ی شکل برابر `pensize/5` محاسبه می‌شود —
+  یک تقریب مستند، نه فرمول دقیق stdlib.
+- **`Turtle.onclick`/`ondrag`/`onrelease`**: تشخیص «روی لاک‌پشت» با یک دایره‌ی
+  احاطه‌کننده است، نه برخورد دقیق نقطه-در-چندضلعی — برای تعامل معمولی
+  (مثل کشیدن با موس) کافی است.
+- **`undo`**: بافر جداگانه برای هر لاک‌پشت (نه یک بافر مشترک سراسری)،
+  و به‌جای بازسازی دقیق مثل stdlib، هر رکورد آنی state قبلی را برمی‌گرداند.
+  همان دستورهایی که stdlib هم undo می‌کند پوشش داده شده: حرکت، چرخش، مهر،
+  نوشته، `dot`، `begin_fill`/`end_fill`، و ویژگی‌های قلم. تغییرات ظاهری مثل
+  `shape`/`tilt`/`resizemode` در stdlib هم قابل undo نیستند.
+- **`bgpic`**: تصویر پس‌زمینه با اندازه‌ی طبیعی خودش وسط‌چین می‌شود (مثل
+  stdlib) — کش داده نمی‌شود که کل پنجره را پر کند.
+- **`textinput`/`numinput`**: با `tkinter.simpledialog` پیاده شده‌اند (چون
+  Arcade دیالوگ ورودی آماده ندارد)؛ یک پنجره‌ی جدا از پنجره‌ی اصلی باز
+  می‌شود. اگر tkinter روی سیستم در دسترس نباشد، خطای مهربان می‌دهند.
+
+### ❌ هنوز پشتیبانی نمی‌شود
+
+`getscreen()` چندپنجره‌ای (فقط یک پنجره در هر زمان)، و `write(move=True)`.
+
+این‌ها به‌صراحت خطای فارسی مهربان می‌دهند، نه رفتار خاموش یا نادرست.
+
+دلیل `write(move=True)`: برای جابه‌جا کردن قلم به انتهای متن باید عرض متن
+اندازه‌گیری شود که به پنجره‌ی باز نیاز دارد، ولی `write()` معمولاً قبل از
+`done()` صدا زده می‌شود. به‌جایش خودت قلم را جابه‌جا کن:
+
+```python
+penup()
+write("سلام")
+goto(xcor() + 60, ycor())
+pendown()
+```
+
+## پشت صحنه چطور کار می‌کند؟
+
+سه تصمیم معماری کلیدی (شرح کامل در [ROADMAP.md](ROADMAP.md)):
+
+1. **صف فرمان واحد**: هر فراخوانی دستور یک «فرمان» به یک صف FIFO مشترک
+   اضافه می‌کند. وضعیت منطقی لاک‌پشت (برای `position()` و مانند آن) بلافاصله
+   به‌روز می‌شود؛ پخش انیمیشنِ آن روی صفحه در فریم‌های بعدی انجام می‌شود.
+2. **تبدیل مختصات متمرکز**: تنها در `_coords.py` — مبدأ Turtle وسط صفحه،
+   مبدأ Arcade گوشه پایین-چپ.
+3. **بافر خط پخته‌شده**: خط‌های تمام‌شده یک‌بار در `ShapeElementList` Arcade
+   ساخته می‌شوند تا نقاشی‌های پیچیده (مثل مارپیچ) کند نشوند.
+
+## اجرای تست‌ها
+
+```bash
+pip install -e ".[dev]"
+pytest
+```